Re: [boost] Google Season of Docs

On Wed, 22 Apr 2020 at 17:54, Paul A Bristow via Boost wrote:

...

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*.

Do you mean use of the so called Doxygen Special Commands like @param, @tparam (or \-prefixed) ?

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 ☹

Yes, I've experienced that too.

...

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.

Seeing adoption of AsciiDoc by some core libraries, I've got a bit excited there may be tools helpful to integrate Doxygen well (e.g. doxygen2adoc perhaps), with a chance to be accepted Boost-wide. Apparently, those libs hand-roll API references, so no priority for Doxygen there. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net