On Sat, 14 Dec 2013 12:04:29 -0800, Andrey Semashev
On Sat, Dec 14, 2013 at 10:15 PM, Krzysztof Czainski <1czajnik@gmail.com> wrote:
2013/12/13 TyRoXx
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?
+1, but I fraze it differently: it would be helpful (not only for beginners) to put the _minimum_ set of #includes in each snippet, and supply namespace information. I find aliasing long namespaces at the beginning of every shown snippet a good idea.
Many libraries' docs have a statement like: "throughout the docs you shoud assume #include
and using namespace boost::thislib;". I think this is bad practice in examples, because it's bad practice in general, and examples should also show good style of using the library. A useful example would be:
#include <list> #include <algorithm> #include
// I'm glad this isn't #include
int main() {
namespace ll = boost::lambda;
std::list<int> v(10);
std::for_each(v.begin(), v.end(), ll::_1 = 1);
}
I mean, it doesn't hurt that much to put the minimum needed #includes and namespace aliases in every snippet. This will not only help beginners, but anyone who wants to copy-paste-modify an example. Could this be made a guidline for Boost docs in general?
I don't think that spelling out all includes and namespaces in examples is a good idea in general. These things clutter the code and draw attention away from the code that is intended to illustrate something. That said it is also important that examples are actual and can be compiled. QuickBook offers a way to achieve this - by importing the compilable examples into the documentation. The version displayed in the docs can be as concise as needed and also contain a link to the compilable version. If anything has to be a guideline, it's this approach, IMHO.
+1 Whichever way, as long as the information is easily located.