Paul Mensonides wrote:
Edward Diener wrote:
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.
These are all completely open-ended and naive questions. There already are examples of problems that have been solved with the pp-lib, yet you say you don't like learning from examples. However, these are just a few possibilities. One of the primary uses of the pp-lib today is repetition of various kinds (the primary use by the Python library and the MPL is in this area), but that is only a small portion of the library. The question of applicability is incredibly context sensitive. I guess my advice in this regard is simple, if it cannot be done reasonably with template metaprogramming, examine whether it is possible to do it with preprocessor metaprogramming--where "it" is a placeholder for whatever you might want to do at compile-time. There are, of course, limitations to both template metaprogramming and preprocessor metaprogramming, but only experience with both can tell you whether something is doable or not or how it might be done.
The various macros need to be grouped in categories which make it easier to understand what functionality exists and why.
These are the categories that actually exist:
- Unsigned saturation arithmetic in the range of 0 to 256. - Manipulation of the "array" data type. - Unsigned numeric comparisons in the range of 0 to 256. - Control flow constructs (such as 'if', 'while', etc.) - Vertical repetition (a.k.a. iteration) - Manipulation of the "list" data type. - Logical operations such as 'and' and 'or'. - Punctuation operators for problem characters like commas and parentheses. - Horizontal repetition constructs - Manipulation of the "sequence" data type. - Evaluated slots. - Manipulation of the "tuple" data type.
...and a host of other non-groupable macros.
It would be a good start to discuss the various categories as subjects of documentation, and illustrate that subject by specifying the various macros which belonged to each category. That way an end-user could gain some idea of the functionality in the pp-lib by a breakdown into manageable ideas and uses. I realize that categories might overlap each other and some categories might need extended discussion while others would need a very short explanation. But breaking down the pp-lib into understandable topics of functionality would make it understandable to the end-user to a much greater degree than just a long alphabetical list of macros which the present documentation presents. I am not trying to cause unnecessary documentation work for you or anybody else in rewards to the pp-lib. If I am the only one having a really hard time attempting to grasp what is there I would say to not do anything further with the current doc. But I have a feeling that their are other programmers who would greatly benefit from a more understandable presentation of the Boost pp-lib functionality. I am willing to tackle the complications of macro expansion and the issues which cause the library to be created the way that it does, if I can feel that the functionality behind it is understandable and useful to me as a programmer.