[boost] Documentation policy about namespaces

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.