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? 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_usa... 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#boo... 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.
On 13/12/2013 19:43, TyRoXx wrote:
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?
Documentation is handled on a per-library basis. The lambda documentation is not as good as it could be as you found out. The maintainer for this library (Jaakko Jarvi) is not very active on the Boost mailing list, you might consider contacting him directly.
2013/12/13 TyRoXx <tyroxxxx@gmail.com>
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 <boost/thislib.hpp> 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 <boost/lambda/core.hpp>
// I'm glad this isn't #include <boost/lambda.hpp>
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? Regards, Kris
On Sat, Dec 14, 2013 at 10:15 PM, Krzysztof Czainski <1czajnik@gmail.com> wrote:
2013/12/13 TyRoXx <tyroxxxx@gmail.com>
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 <boost/thislib.hpp> 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 <boost/lambda/core.hpp>
// I'm glad this isn't #include <boost/lambda.hpp>
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.
On Sat, 14 Dec 2013 12:04:29 -0800, Andrey Semashev <andrey.semashev@gmail.com> wrote:
On Sat, Dec 14, 2013 at 10:15 PM, Krzysztof Czainski <1czajnik@gmail.com> wrote:
2013/12/13 TyRoXx <tyroxxxx@gmail.com>
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 <boost/thislib.hpp> 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 <boost/lambda/core.hpp>
// I'm glad this isn't #include <boost/lambda.hpp>
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.
On Sat, Dec 14, 2013 at 10:23 PM, Mostafa <mostafa_working_away@yahoo.com>wrote:
On Sat, 14 Dec 2013 12:04:29 -0800, Andrey Semashev < andrey.semashev@gmail.com> wrote:
On Sat, Dec 14, 2013 at 10:15 PM, Krzysztof Czainski <1czajnik@gmail.com>
wrote:
2013/12/13 TyRoXx <tyroxxxx@gmail.com>
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
-- Marco
----- Original Message -----
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?
+1 Speaking as somebody who has been hitting the boost docs hard in the last few months, #includes and namespaces with every snippet is *exactly* what I wished there were more of. I spent a fair amount of time guessing, or finding other examples on stackoverflow, etc.
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of TyRoXx Sent: Friday, December 13, 2013 6:43 PM To: boost@lists.boost.org 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 +44 1539 561830 07714330204 pbristow@hetp.u-net.com
participants (8)
-
Andrey Semashev -
Erik Erlandson -
Krzysztof Czainski -
Mathias Gaunard -
Mostafa -
Paul A. Bristow -
sguazt -
TyRoXx