Re: [boost] Google Season of Docs

-----Original Message----- From: Boost On Behalf Of Mateusz Loskot via Boost Sent: 22 April 2020 16:45 To: boost@lists.boost.org Cc: Mateusz Loskot Subject: 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.

Definitely - NIH still rules the computing world☹ (NIH == Not Invented Here).

Does that show the weakness of Doxygen?

No - because almost no libraries use Doxygen as it should be used IMO. They do not add Doxygen syntax docs info *as they are writing the code*. And I absolutely sympathize - writing code is hard enough and documenting is a distraction. By the time one has got something working, energy to document is near zero ☹

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.

Strongly agree - it's a mess - and that's why I would like to make the most popular toolchain work better, and be used better. But I've been bleating for years... and I'm stack-overflow with other projects already. Paul