Re: Google Season of Docs

From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2020-04-22 14:59:44

Dear Paul,

> On 22. Apr 2020, at 14:55, Paul A Bristow via Boost <boost_at_[hidden]> wrote:
> 
> +1 Doxygen Syntax comments are THE standard way of describing expected code
> performance.
> 
> Doxygen now understands C++ (using the Clang compiler so it really does ).
> 
> What the parameters and template parameters do, what items are updated, what is
> returned, and of course, what a function does.
> 
> (The magic of how and why may be an added bonus).
> 
> Authors/documenters have to write this by hand - not just feed the code into
> Doxygen!  (which is the delusion that many suffer from).
> 
> Quickbook and other tools can process this info (because it has a known
> standard-ish syntax) and display it nicely.

I wish it was so. Our toolchain does not handle meta-functions such as this:

/** 
  This is a meta-function. Bla bla.
*/
template <class T>
using enable_if_t = ....

The problem already exists in the XML code that the doxygen rule in a Jamfile generates. I don't know whether this is a problem with the rule or doxygen itself. The doxygen rule from Boost.Build is non-trivial and I haven't tried to run doxygen myself. I cannot read Boost.Build scripts very well, but it looks like the rule does some post-processing of the original XML.

The workaround that I copied from other Boost libs is to do stuff like this

#ifdef BOOST_HISTOGRAM_DOXYGEN_INVOKED

// code that doxygen understands

#else

// actual code

#endif

This is, of course, terrible. If anyone has a better solution for this, I would love to document my meta-functions differently.

There are other issues. Doxygen includes stuff that I don't want to show, unnamed template parameters, stuff that is in my boost::histogram::detail namespace, private member functions (although I configured it not to show them...).

I have a Python script that does post-processing on the XML file produced by the doxygen rule in the Jamfile, where I fix all this, where I remove items marked as deprecated, and where I sort the headers in the reference alphabetically. All this should work out of the box.

Best regards,
Hans