Subject: [boost] Documentation policy about namespaces
From: Lasse Kärkkäinen (tronic+67zr_at_[hidden])
Date: 2009-08-02 12:41:53
I couldn't find any discussion about this, but I have noticed that the
documentation often completely neglects to mention the namespaces used
or just mentions somewhere which using namespace directives should be
used instead of documenting the namespaces of individual symbols.
To me it would seem best to use explicit namespace specification in all
example code and reference documentation. However, in example code where
this is unsuitable (e.g. boost::placeholders::_1), the required using
declarations and directives should be documented along with which
symbols they are used for.
Adding the namespace information to the documentation increases clarity
because it instantly tells the reader which symbols are part of the
library and which are part of the example code. Additionally, a number
of Boost libraries already use the same symbol names in their respective
namespaces, so assuming a large collection of using namespace directives
is a bad practice.
Documenting the header files to use and the libraries to link is another
similar issue, but the problem is not as severe as it is with namespaces.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk