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, doxygen@... 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 doxygen@...
> Web page http://jaredharvey.com
>
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Doxygen-users mailing list
> Doxygen-users@...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
|