Re: [boost] Improving Documentation

On Sat, Oct 12, 2013 at 12:59 PM, Paul A. Bristow wrote:

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrew Hundt Sent: Friday, October 11, 2013 8:42 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On Fri, Oct 11, 2013 at 2:49 PM, Robert Ramey wrote:

...

Mathias Gaunard wrote:

...

On 11/10/13 15:31, TONGARI J wrote:

...

I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

what about the type constraints - aka concepts? and templates?

You can document template parameters with doxygen. If you are using the boost concept check library you can also use those classes to document your concepts. I believe gil does that if you would like an example. You can also always add custom fields fairly easily if none of the existing ones meet you needs.

You can also document \pre and \post conditions - aka 'concepts'.

This with \returns \param and \tparam allows one to match the info and style of SGI style documentation (but with hyperlinking).

(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 the real code more cluttered.