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

Subject: Re: [boost] Why do many examples lack #includes and namespaces?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-12-16 05:30:20

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of TyRoXx
> Sent: Friday, December 13, 2013 6:43 PM
> To: boost_at_[hidden]
> Subject: [boost] Why do many examples lack #includes and namespaces?
> 
> 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?

You are quite right - the user needs to know these things.

But there is a big risk of confusion/clutter/tedious repetition  if you *always* include this
information.

So the best documentation, usually using Quickbook, provides snippets (like the one above), with the
key message,

probably also adding inline comments (or callouts for longer expanations)

but also a link the full example's code so one can download it and run it (or cut'n'paste from it).

It takes time and authors are often exhausted by the task of producing the C++ code and getting over
the cross platform/compiler hurdles.

Quite a few older libraries could usefully be updated in this style to avoid the sort of user
frustration that you have endured.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]