Re: Google Season of Docs

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2020-04-22 15:45:28

On Wed, 22 Apr 2020 at 17:00, Hans Dembinski via Boost
<boost_at_[hidden]> wrote:
> > 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
> > 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