Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-14 04:11:53

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey Semashev
> Sent: Saturday, October 12, 2013 10:31 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation
> 
> > (and there are others like \sa = see also).
> 
> While I agree with you that Doxygen is a great tool for generating reference sections, when I was
writing
> Boost.Log docs I found that Boost stylesheets discarded most of the special tags (AFAIR, \sa was
one of
> them; \cond doesn't always work, I don't remember the others).

OK - more work now - and all *could* be made to work - we just need to encourage Steven  Watanabe or
someone to fix the XSTL code that handles them.  The Quickbook admonitions work nicely and look just
like in Quickbook.

> This was particularly frustrating because //! style comments for functions would not get into docs
(the
> functions would appear undocumented). Also formatting for some long declarations (e.g.
> functions with long return/argument types) is not always pretty. These problems sometimes require
> quite an amount of scaffolding just to make the code look well in the docs, which actually makes
the real code more cluttered.

But at least the comments are with the code - something that as reader of code I very much like.
And it reduces the risk of mismatch between comments and code compared to separate files.

Syntax coloring comments in a suitable color (I much prefer green) makes them more or less disappear
for me when trying to read the actual code.

Can I make a concrete suggestion?  That we take an existing library (whose docs we don't like much)
and I (and anyone else who wants to contribute) will try to redo the docs using Quickbook/Doxygen
for C++ reference section and AutoIndex and try to see how far we can meet people's needs/wishes.

I would suggest Units - but it is a bit big.

(Boost.Math would be excellent - but it is dauntingly big!)

Ideas?

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]