Paul Mensonides wrote:
Edward Diener wrote:
Paul Mensonides wrote:
Markus Werle wrote:
Ah! Earning money with Open Source via Closed Docs ;-) Not exactly what RMS was dreaming of, but perfectly OK for me: I will buy that book ASAP. I hope You also explain all those macros that make the code so uneasy to read.
I think your talking about the usage of the preprocessor lib here. If David and Aleksey are writing a book on the MPL, they've got enough on their plate without trying to explain the pp-lib also.
The doc on the pp-lib really needs to be better. I admit I gave up trying to understand it because I really don't waste my own time anymore reading bad documentation, even though I know many people consider adequate documentation what I consider bad. I am sure there is much good functionality in the pp-lib and that many people understand it but I don't think I ever will.
Actually, there are only a few that understand the implementation--mostly because there are only a few that actually care to. Do you want to understand how it works? Or do you want to understand its interface and how to use it? Or, do you want to understand _when_ to use it?
I really do hope the pp-lib people take it to heart that they need to provide better doc about it which explains it from the ground floor up.
What specifically would you have me do? The pp-lib docs do not attempt to explain the implementation of the pp-lib itself.
I don't want an explanation of the inner workings of the pp-lib. I would like to see an explanation of the pp-lib which attempts to explain the functionality of it from the user's point of view. Something like a grouping of the macros in it from the point of view of general areas of functionality, with the specific macros grouped and explained within each area. The topic section does not do this. Instead it jumps around through various ideas I find almost impossible to understand. Furthermore nearly everything is done at this level by showing examples rather than explaining what things are. I admit I hate this mode of explaining computer programming which gives an example with little explanation and an attitude of "get it yet ?". Documentation needs to explain concepts in a regularized way and present them to the end user slowly and logically so that people can build up an understanding of things to do. Take the beginning motivation topic. I am told, as an example of the pp-lib, that the library can make it easier to generate repetitive overloaded metafunctions. Then at the bottom I am shown a series of Boost preprocessing macros to do this which are completely non-understandable to anyone coming to the pp-lib. I skip the "known problems of the preprocessor section" and go on to techniques. Here I am presented with a series of examples before any macros have been explained. This is documentation ? I have no ideas what these macros are or what they do. The second technique mentions using BOOST_PP_EMPTY and then this doesn't appear in the example at all. I am then told to use various pp-lib macros for various general tasks without any explanation of what these macros are and what they do. Again this isn't documentation as I define it. The next section of incompatibilities mentions various macros with again no explanation of what these are about. Etc. etc. Now I realize there is a reference section which lists each macro alphabetically. But this isn't to me an explanation of the areas of functionality of the pp-lib presented in any logical order. What the pp-lib docs need is a logical explanation of its functionality so that others may understand what is being done here, why it is being done, and how it is supposed to be used to supplement normal C++ programming, whether that programming involves template programming or otherwise. I don't mean to be harsh in my criticism of the documentation but to me it was created for the already "initiated" and not for the C++ programmer who is trying to gain an idea about the functionality of the preprocessor library as to each of its general parts and uses. The doc needs to be rewritten and presented in a logical manner to those who are coming to the pp-lib for the first time and are trying to understand its purpose and what problems it hopes to solve or what programming tasks it hopes to make easier. The various macros need to be grouped in categories which make it easier to understand what functionality exists and why.