Re: Google Season of Docs

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

On Wed, 22 Apr 2020 at 17:54, Paul A Bristow via Boost
<boost_at_[hidden]> wrote:
> > 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.
>
> 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