Re: [Doxygen-users] @include inquiry?

[Daniel R. <dr...@gm...>]

To give a not entirely useful answer, I never could get doxygen to reliably document code that was generated by macros. Things that would work in one version, would then fail in the next, making it hard to produce code that would allow people to generate the docs on the variety of systems we had around the office. My solution was to use a python script as a filter which stripped out the "unwanted" includes and then ran the file through cpp to expand the desired macros (which were only defined in a few places to aid in the usage of swig and, hence, simple for the script to feed to cpp).  Not the best solution, but it ended up being much easier to implement than any alternative I could find.
            --Daniel



On May 23, 2010, at 5:40 AM, do...@ja... wrote:

> Hello doxygen-users,
> 
> I'm  trying  to  get  an  include  statement to be
> better  documented  when  generating Doxygen docs,
> and  I'm  having some trouble. Or at least I think
> I'm  having  trouble.  There  is  a chance that my
> expectations  about  what should happen, is simply
> happening in a different manner.
> 
> The  chunk  of  code I'm trying to better document
> uses  a  couple  #define  statement, then #include
> statement which expands such that you can have one
> section  of  code,  that will update several other
> pieces of code. These expanded chunks of code have
> matching prototypes defined else where.
> 
> Currently   the   doxygen   docs   will  find  the
> prototypes,  but  won't list the expanded code for
> those    prototypes.   I've   added   a   "@brief"
> description   that   helps   explain   this  macro
> approach,  but  it would be nice to see the actual
> expanded  code.  From  what  I've read, it appears
> that  should  be  possible  with  the  @include or
> /include doxygen command. However I can't get this
> include  command  to  work as I expect it to work.
> Here's an example.
> 
> Both  these  files are in the same directory, In a
> file called b.c I have this.
> 
> /** @file b.c
> *  A brief brief desc b.c.
> *  A less brief description for b.c.
> *  @brief b.c brief desc.
> */
> 
> /* @ include a.c */
> #include "a.c";
> 
> Then in a file titled a.c I have this.
> 
> /** @file a.c
> *  A brief temp brief desc.
> *  A less brief description for a.c.
> *  @brief a.c brief desc.
> */
> 
> /* @include /mnt/mythdora5/home/mythtv/freeEMS/git-copy/freeems-vanilla/src/temp/inc/proto.h */
> #include "inc/proto.h"
> 
> int  main(){ 
>        // some code
>        /* Channel 1 */
>        #define CHANNEL_NUMBER 1
>        /** @include inc/XISR.h */
>        #include "inc/XISR.h"
>        #undef CHANNEL_NUMBER
> 
>        #define CHANNEL_NUMBER 2
>        /** @include inc/XISR.h */
>        #include "inc/XISR.h"
>        #undef CHANNEL_NUMBER
> }
> 
>> From here,
> 
> http://www.doxygen.nl/commands.html#cmdinclude
> 
> I  expect  the  above  include command from b.c to
> simply  cut  and  paste the a.c file into b.c, the
> the resulting file is sent to the parser. However,
> that  doesn't  appear  to  be  what  I  see in the
> doxygen docs. Instead I get this text.
> 
> Detailed Description
> 
> b.c brief desc.
> 
> A brief brief desc b.c. A less brief description for b.c.
> 
> Definition in file b.c.
> 
> That's  about  it. Also after browsing to the code
> listing,  it simply shows what is in the file, not
> a  version  that includes the a.c file, like I was
> expecting.
> 
> Here are some key notes from Doxyfile.
> 
> # Doxyfile 1.6.1
> EXAMPLE_PATH = inc \ .
> EXAMPLE_PATTERNS = *
> ENABLE_PREPROCESSING = YES
> MACRO_EXPANSION = YES
> SEARCH_INCLUDES        = YES
> INCLUDE_PATH = inc \ .
> INCLUDE_FILE_PATTERNS = *
> 
> So I guess the first thing I should inquire about,
> is  there  a  way to get doxygen to expand include
> files, such that a file with a prototype will show
> the  actual  code?  If  yes,  then is @include the
> correct  command  or  approach?  If  yes, then why
> doesn't    what    I've    drafted   produce   the
> documentation I was expecting?
> 
> Thanks in advance.
> 
> Best regards.
> 
> .. ..-. / -.-- --- ..- / .-. . .- -.. /  - .... .. ...   
> .-.. . - ... / .... .- ...- . / .- / -... . . .-. 
> 
> Jared Harvey                           Operator KB1GTT
> 
> e-mail do...@ja...
> Web page http://jaredharvey.com
> 
> 
> ------------------------------------------------------------------------------
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users