Geometry Boost List: [ggl] Documenting parameters

Subject: [ggl] Documenting parameters
From: Mateusz Loskot (mateusz)
Date: 2010-10-19 20:08:32

Hi,

The new version of documentation has merged the description of template
parameters with run-time call parameters. I am not convinced it's a good
idea. In the previous version, there were two tables: Template
parameters and Parameters.

For instance, in area.qbk, reading the Parameters table I don't think
it's sufficient documentation.
Description of requirements of object parameters (arguments of
functions, constructors, etc.) is one thing, but description of template
parameters is another thing.
I think it would be good to separate them. I like how it is done
in Boost.Asio. For instance:

http://www.boost.org/doc/libs/1_44_0/doc/html/boost_asio/reference/async_read/overload1.html

Note, how neatly the templates are documented. Name of template
parameter is a link to description of concept / requirements
which should be modelled by type passed to the template.

What you think?

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org