Re: Google Season of Docs

From: pbristow_at_[hidden]
Date: 2020-04-22 15:54:36

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Mateusz Loskot via
> Boost
> Sent: 22 April 2020 16:45
> To: boost_at_[hidden]
> Cc: Mateusz Loskot <mateusz_at_[hidden]>
> Subject: Re: [boost] Google Season of Docs
> 
> 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*.

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