Re: Understanding MPL

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-04-02 07:18:01

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.