From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2020-04-22 14:59:44
> 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
> 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
// code that doxygen understands
// actual code
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk