Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-12 12:55:57

Paul A. Bristow wrote:
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
>> Andrew Hundt

>> 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'.

To me, pre/post conditions are something entirely different than
type requirements.

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

I did spend some time with this but was unable to get something
that worked to my satisfaction.  I reluctantly gave up on Doxygen
because I felt I would have had to spend a lot of time making
another "layer" to handle the stuff I thought was missing.  I was
reluctant because I thought that Doxygen was on the right
path - literate programming - but didn't really support the kind
of programming we do here at boost.  I believe that this view
is supported by the Doxygen documentation we see here. Mostly
it seems that it's short version of the header with some live links
which point somewhere else - which is totally backwards in
my opinion.  I don't see how this can really work for templaltes.
It's also not much more helpful than just browsing the source
code headers - which in many cases I end up having to do
anyway.

Robert Ramey