Subject: Re: [boost] Improving Boost Docs
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-08-16 15:09:03
On Wed, Aug 16, 2017 at 8:03 AM, Robert Ramey via Boost
> b) The inclusion of all the specialized tags for C++ like class, struct, is
> meant to automate the production of boiler plate output for those C++
> constructs. I understand the appeal of this - we're computer programmers
> and want to automate everything - but in this case it's a bridge too far.
> quickbook doesn't use these - a good choice in my opinion. A few hand
> edited boost book do uses these but the results are not satisfying in my
> opinion. To improve them, one would have to wade into XSL language - a
> place were few people want to go.
And again I will use this opportunity to point out that I have "gone
there" by creating "docca", an XSL library which provides the
component for transforming Doxygen XML output into QuickBook:
Beast uses docca directly to generate its reference section.
Everything linked from this reference index was generated using
Doxygen + docca:
(The index itself is hand-written).
I realize of course that this style of reference is not suited for all
types of libraries. For example, it would not do very well with mp11
or Hana. But for a more traditional library that has mostly concrete
types and functions it works pretty well. Note that Asio uses an
identical toolchain (well, I copied it).
If anyone is interested in a docca integration for their library, to
generate a reference from Javadoc comments in the code using Doxygen,
I would be happy to help.