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 12:27:51

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of John Maddock
> Sent: 01 February 2016 18:26
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] How to ensure that Boost option macros appear in the Doxygen generated
> index?
> 
> 
> 
> 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
> */

But this doesn't make Doxygen process the information provided in the \def statement, so it doesn't
appear in the C++ reference section :-(
 
> 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

I've tried adding  BOOST_SOME_OPTION to the .idx file, but this means that you do get an entry in
the main index, but not the specific macro index, and the information provide in the \def statement
is also missing.

I've already done what Kirit Saelensminde says that he find works for his project(s)

"put some extra .cpp and .hpp files in there that I gave to Doxygen but weren't included in the
build. "

This file contains #define BOOST_SOME_OPTION ...

I think that it is a messy solution, not keeping everything in one place.  If you add another
optional BOOST_SOME_OTHER_OPTION, then you've got to remember to add this to the doxygen_defines.cpp
file as well.

(There is a never-ending conflict/compromise between putting it all in the C++ code file and having
separate files with documentation.  I'm very firmly in the 'all-in-one-place' camp.)

In this case if you want an Boost.Autoindex index of macros, then it is almost three places.

(In future, if Doxygen is using the Clang compiler to parse the code, maybe we can pass
-dBOOST_SOME_OPTION so this stage will trigger Doxygen to processor the information about the macro
as I wish).

Perhaps there is, or can be, some way to tell Doxygen that \def ... stuff should be process, even if
not defined?
I have now also asked on the Doxygen bugzilla about this.

Paul

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