Re: [Boost-docs] How to ensure that Boost option macros appear in the Doxygen generated index?

Subject: Re: [Boost-docs] How to ensure that Boost option macros appear in the Doxygen generated index?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-02-02 17:06:30

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Kirit Sælensminde
> Sent: 02 February 2016 03:09
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] How to ensure that Boost option macros appear in the Doxygen generated
> index?
> 
> On 02/02/16 01:13, Paul A. Bristow wrote:
> > Can I force documentation of the macro symbol other than by nasty
> > fudges like
> >
> >     #define BOOST_SOME_OPTION
> >     #undef BOOST_SOME_OPTION
> The way I always did this was to have a docs folder and put some extra .cpp and .hpp files in
there
> that I gave to Doxygen but weren't included in the build. That way you can have whatever you need
> to get it to index things as you want without tainting your code.
> 
> I also found it a much more useful place to put longer explanations so I didn't clutter up all of
the
> code with it (and didn't have to recompile when fixing typos etc.).

http://stackoverflow.com/questions/35090656/doxygen-how-can-i-document-macros-that-are-not-defined

provided a simpler and better solution.

(Sadly also revealing that I should have done more RTFM - again :-(  
see and understand https://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html)

Bracket all the (not-default) option macros inside an ifdef - endif  like this

    #ifdef BOOST_DOXYGEN_GENERATION

    #  define BOOST_SOME_OPTION
    #endif

then use the doxyfile PREDEFINED= BOOST_DOXYGEN_GENERATION option, in my case by adding

    <doxygen:param>PREDEFINED=BOOST_DOXYGEN_GENERATION

to my jamfile.v2

which will ensure that BOOST_SOME_OPTION appears in an overall index, 

BOOST_SOME_OPTION
Header < boost/quickdox/quick_auto_dox_index.hpp >
Macro BOOST_SOME_OPTION

so you can go directly to the header file containing the macro (non-)definition and its
documentation,
or see the resulting documentation itself.

Also allowing, if desired, a separate index of all macros, including any that are options:

[named_index macro_name Macro Index]

provided you have as first include in Quickbook file auto_index_helpers.qbk

[import ../../../tools/auto_index/include/auto_index_helpers.qbk]

This is especially useful for libraries that offer lots of mysterious BOOST_ options.

Thanks all for their advice.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]