Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2013-10-12 05:31:13

On Sat, Oct 12, 2013 at 12:59 PM, Paul A. Bristow
<pbristow_at_[hidden]> wrote:
>
>
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrew Hundt
>> Sent: Friday, October 11, 2013 8:42 PM
>> To: boost_at_[hidden]
>> Subject: Re: [boost] Improving Documentation
>>
>> On Fri, Oct 11, 2013 at 2:49 PM, Robert Ramey <ramey_at_[hidden]> 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.