Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-05 16:24:50

On 1/5/16 3:14 AM, Paul A. Bristow wrote:

> IMO, any new documentation toolchain needs to provide a way of using documentation provided as
> comments in the C++ code itself, probably using the syntax of Doyxgen comments that are now
> processed by Clang and Microsoft compilers - this syntax (not necessarily the Doxygen tool itself)
> is being pretty much standard.

As far as I'm concerned, The usage of Doxygen and the perception that 
it's effective for documentation for templated classes is one of the 
main causes of poor C++ documentation.  It's harmful.
>
> The current method doing this is a bit clunky and slow to build, but it does allow the document
> writer to provide hyperlinks to these bits of vital information about parameter, template
> parameters, functions, returns, exceptions etc...

and it's complicated the documentation toolchain.

So it's generates a lot of effort to create poor documentation.  If 
Doxygen is to be used, there needs to be serious effort to extend it in 
some way.  I believe it does have an extension capability.

Robert Ramey