[Doxygen-users] @include inquiry?

[<do...@ja...>]

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