Hello,
I've added a new configuration tag to my local copy of Doxygen (attached
are the results of running "cvs diff -u" against the two modified files,
doxygen.cpp and config.l, against the CVS version as of 15:30 GMT
Thursday November 1st).
With these changes in place, if you set EXAMPLE_RECURSIVE to YES and
RECURSIVE to NO then files used for examples, using \dontinclude and
\include, will recursively search from EXAMPLE_PATH without also
allowing the INPUT directories to be recursively scanned. Set
EXAMPLE_RECURSIVE to NO (the default) and nothing has changed.
This change makes \dontinclude and \include usable with the way that I
have the source code for libraries arranged:
projects/lib1/-+-m/
|
+-dox/
where projects/lib1/ contains all the *.h files required to _use_ the
library (the interface) and projects/lib1/m/ contains the implementation
of the library (all the *.cpp etc and a number of *.h that contain
implementation details and some more files of Doxygen comments).
projects/lib1/dox/ contains files with Doxygen comments for all the long
items that should not go into normal source modules, such as as
dissections of examples that illustrate how to use the library (using
\include etc), which I happen to put into files ending in ".dox".
There is a separate examples directory tree:
projects/examples/-+-lib1/-+-eg1/main.cpp
| |
| +-eg2/main.cpp stuff.cpp thing.cpp
|
+-/lib2/eg1
etc.
BTW there are very real reasons for this structure - well, the _real_
structure, which
is even more complicated than the above - but that will suffice :-)
I generate two lots of Doxygen output, one for people who want to use
the library and one for those who want to know the implementation
details; the main difference between the Doxygen configuration files are
that the user-level one has
@INCLUDE = common-config.doxy
INPUT = . ./dox
FILE_PATTERNS = *.h *.dox
RECURSIVE = NO
EXAMPLE_RECURSIVE = YES
whilst the implementation one has
@INCLUDE = common-config.doxy
INPUT = .
FILE_PATTERNS = *.h *.dox *.cpp
RECURSIVE = YES
Within lib1/dox/ there are dissections of the the examples, eg1 and eg2,
which start with:
\dontinclude lib1/eg1/main.cpp
and
\dontinclude lib1/eg2/main.cpp
Without the new EXAMPLE_RECURSIVE tag, this arrangement would always
work for the implementation documentation, but for the user
documentation, with RECURSIVE=NO, the examples would not be found or, if
one set RECURSIVE=YES, the examples _would_ be found but (some of) the
details of the implementation would also be dragged in.
I hope this is of interest,
Regards,
Stephen Goudge
|
