[boost] Why do many examples lack #includes and namespaces?

Subject: [boost] Why do many examples lack #includes and namespaces?
From: TyRoXx (tyroxxxx_at_[hidden])
Date: 2013-12-13 13:43:03

The first example for Lambda 1.55 is:

list<int> v(10);
for_each(v.begin(), v.end(), _1 = 1);

This is not useful at all.
The first two question that every new user would ask are:

- which header files do I have to include?
- which namespaces are the things from? Is _1 the global that I already 
know from bind or not?

A useful example would be:

#include <list>
#include <algorithm>
#include <boost/lambda/core.hpp>
int main() {
   std::list<int> v(10);
   std::for_each(v.begin(), v.end(), boost::lambda::_1 = 1);
}

I cannot even find the usual .cpp example files anywhere on
http://www.boost.org/doc/libs/1_55_0/doc/html/lambda.html
.

I have been using Boost for a long time so I knew that Lambda headers 
would probably be in a directory called boost/lambda/. I also knew that 
list and for_each would most probably come from the standard library. 
But not everyone does!
Material for beginners, especially "examples", should be compresensible. 
I do not understand why that is not the case for so many Boost libraries.

Some libraries are telling you the namespace but not the headers:

- DateTime
- Function
- Signals2 in the tutorials
- Array (the only example is in the "Design Rationale")
...

http://www.boost.org/doc/libs/1_55_0/doc/html/date_time/examples/general_usage_examples.html
http://www.boost.org/doc/libs/1_55_0/doc/html/function/tutorial.html
http://www.boost.org/doc/libs/1_55_0/doc/html/signals2/examples.html
http://www.boost.org/doc/libs/1_55_0/doc/html/array/rationale.html

Some libraries have better examples:

- Atomic has useful examples with #includes and namespaces.
- Random has very useful examples, too.
- Unordered has minimal, but useful examples on the main page.
...

http://www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html
http://www.boost.org/doc/libs/1_55_0/doc/html/boost_random/tutorial.html#boost_random.tutorial.generating_integers_in_a_range
http://www.boost.org/doc/libs/1_55_0/doc/html/unordered.html

I am talking about the HTML documentation only.

That's all for now.