Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2017-10-10 09:12:14

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey via Boost
> Sent: 09 October 2017 18:02
> To: Paul A. Bristow via Boost
> Cc: Robert Ramey
> Subject: Re: [boost] Asciidoc, an alternative for documentation
> 
> On 10/9/17 9:08 AM, Paul A. Bristow via Boost wrote:
> > Doxygen syntax mark-up is the key to any tool to process well. The quality of the in-code documentation is of paramount
> importance.
> > No tool can compensate for what is missing here.
> >
> > I think we should judge*future*  libraries by the quality of this - so that future tools like this can (re-)process it to
produce
> > future documentation.
> 
> Hmmmmm - what does "this" refer to here? in each place?

Sorry I wasn't clear : I believe that

Comprehensive Doxygen syntax mark-up in-code is very important.

(Even if it isn't used to generate the current documentation).

(And I know that some people don't like it because it clutters the actual code, but I find syntax colouring allows the brain to skip
over the comments when reading the code - and vice versa).

Paul

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