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