-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Saturday, October 12, 2013 10:31 AM To: boost@lists.boost.org 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).
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
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. 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 +44 1539 561830 07714330204 pbristow@hetp.u-net.com