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-10 15:28:03

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Soul Studios
> Sent: 09 January 2016 21:53
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] [boost-docs] Query regarding boostbook and documentation
> 
> > b) DOxygen is here to stay.  I would like to see someone take up the
> > challenge of making an extension which supports type requirements (aka
> > concepts).
> >  From the users point of view, this would look like the following:
> 
> I personally would not want to see Doxygen becoming a requirement, though I understand many like
> it. 

> Personally I find it an impediment to writing clean, readable code.

In an ideal world with an ideal language, the source code itself would be sufficient (given
sufficiently long variable names) to be self-documenting.

But C++ is a language where, in order to achieve wonderful things, it is necessary to use lots of
cunning tricks.

(This is especially true for Boost libraries - many consist almost entirely of cunning tricks! )

So we need more information somewhere and somehow.

We have to choose between:

1  putting documentation info  in the same file, cluttering the code with comments, or 

2  in a separate file meaning a more complex structure, and more files, and a mechanism of linking
code items like class names and their documentation info.

On balance, keeping it simple with both code and documentation info in the same C++ file seems more
popular.

(Using syntax-coloring can quickly allow the brain to separate C++ code from comments - unless you
are color-blind).

And we need a *syntax* so that documentation info can be machine processed.  Given lots of 'prior
art' and existing tools, I conclude that the Doxygen Syntax is the only sensible de facto
'standard'.

To deal better with templates and meta-template programming we probably need extensions to the
existing syntax.

Paul

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