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

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-06 10:59:33

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Robert Ramey
> Sent: 05 January 2016 16:25
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] [boost-docs] Query regarding boostbook and documentation
> 
> 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.

I violently disagree with this - it not ideal, but the best documentation syntax we have yet.

But I do agree that Doxygen needs to work better for templated classes.  Getting it to use Clang
instead of its own parsing is key to this and recent versions are making good progress with this.  

What is vital is that there is some way to documentation what each parameter (and template
parameter) does, the constraints, preconditions, postconditions, returns, exceptions, throws (or
not) etc (even examples of use). 

This needs to be written as the code is written - or it never will be.

Using the Doxygen *syntax* is one way of doing this and the only way that is remotely 'standard'.
If we want to convert to a C++ Language Concepts syntax, this could be done mechanically later. 

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]