Re: [boost] Google Season of Docs

On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost wrote:

...

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. [...] There are other issues. [...] I have a Python script that does post-processing on the XML

Asio developed XSLT, Beast developed XSLT, Geometry initially developed XSLT, but switched to bespoke XML processor C++/Python. and these are not trivial solutions at all. Authors of new libraries will look at these and within 5 minutes decide to develop their own solution, I bet. Does that show the weakness of Doxygen? To me it somewhat does and the lack of Boost common solution is a motivation to avoid Doxygen. It may be a personal preference, but I very much dislike the (freedom of) variety of look & feel of documentation of Boost libraries. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net