Re: [boost] Google Season of Docs

Dear Paul,

On 22. Apr 2020, at 14:55, Paul A Bristow via Boost 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