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: John Maddock (jz.maddock_at_[hidden])
Date: 2016-02-01 18:25:53

On 01/02/2016 18:13, Paul A. Bristow wrote:
> I am trying to Doxygen document the functions of some option-controlling macros symbols in a header
> file, for example, my boost_header.hpp:
>
>      //! \def BOOST_SOME_OPTION
>      /*! \brief Option macro that is not normally defined
>      but can optionally be defined by consumers to activate the option.
>      */
>
> But this will @b NOT be indexed and the comment ignored because the macro isn't defined.
>
> This only produces an Doxygen macro symbol entry in the documentation when there is a #define like
>
>      #define BOOST_SOMEFEATURE
>
> in the header and other files.
>
> Can I force documentation of the macro symbol other than by nasty fudges like
>
>     #define BOOST_SOME_OPTION
>     #undef BOOST_SOME_OPTION

What about something as simple as:

/*
// Uncomment if you need this:
#define BOOST_SOME_OPTION
*/

Otherwise you're looking at changing the scanner rules used in the .idx 
file or adding the macros manually to that file using:

BOOST_SOME_OPTION "" "" macro_name

etc.

HTH, John.

> (Will this produced spurious but worrying warning about redefinition?)
>
> I can achieve my objective by including a dummy macro_defines.cpp file that contains #defines for
> all the macro symbols that control options?
>
>    #define BOOST_SOME_OPTION
>    #define BOOST_SOMEOTHERFEATURE
>    ...
>
> but I have to remember to do this, and add all the new options as they are conceived, and also to
> add this macro_defines.cpp filename to the list of files fed to Boost.Autoindex in the .idx file,
>
> and this file is added to the list of files processed by Doxygen in the jamfile.v2.
>
> Then (with a  I get an entry for [named_index macro_name Macro Index] in the .qbk file) I get an
> entry as expected
>
> "
> Macro BOOST_SOME_OPTION
>
> BOOST_SOME_OPTION - Macro to control some optional feature (But if this is neither defined nor used,
> then this will NOT be indexed and the comment ignored, unless the macro is defined.)
>
> Synopsis
>
> // In header: <doxygen_generation.cpp>
>
> BOOST_SOME_OPTION
>
> Description
>
> So a separate file .cpp is written that contains a #define
> #  define BOOST_SOME_OPTION
> "
>
> This is tedious and error-prone :-(
>
> Can anyone suggest a better way?
>
> Thanks
>
> Paul
>
> ---
> Paul A. Bristow
> Prizet Farmhouse
> Kendal UK LA8 8AB
> [phone]
>
>
>
> _______________________________________________
> Boost-docs mailing list
> Boost-docs_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-docs
>