On 08/05/2014 6:44 PM, Robert Ramey wrote:
As of now, I'd say that the STL documentation provides a good starting point for the documentation structure of most libraries (maybe all, I don't know). But adaptations might be required to make it fit to specific libraries.
I make my case in http://rrsd.com/blincubator.com/requirements_documentation/
Tutorial documentation of course is another issue so exclude that for now.
For what it's worth -- from the viewpoint of a newcomer to Boost (and someone who is not a developer by profession) -- I've really found the lack of consistency of documentation to be a major challenge in terms of learning what libraries are most applicable to my own needs, and how to use them. I think that there are 2 separate issues involved here: The first is layout/structure of the documentation itself, as Robert suggests in this and previous comments. The second -- and from my personal experience, the more difficult -- is the lack of a consistently-written and sufficiently descriptive explanation of the 'what, where, why, and how' of the library: What does the library do? Where should I use it? Where should I not use it? Why (explain the overall design -- why is the library structure like X)? How do I use it? I completely understand the extreme difficulty involved in trying to enforce a specific style and format of the documentation on the library authors. It has already been suggested -- whether one agrees with it or not -- that not all libraries can even fit into the same structure due to the paradigm mismatch. Perhaps this suggests that an approach to documentation standardization should take this into account -- in terms of care of not over-specifying the requirements.
Basically reference documentation contains a list of:
named type constraints (concepts) types and parameterized types functions
From my own perspective, the documentation I've read which has followed this general approach has been much easier for me to follow. On the topic of Concepts-- The issue of Concepts is clearly quite contentious; however, what does seem clear to me from following this thread is that many people believe that Boost.Concept is lacking. What is not clear to me is whether there is significant disagreement about how Boost.Concept (or its successor) should look/behave. In other words- is there any consensus on what is expected from Boost.TypeRequirements (or whatever name might better be suited to Boost.Concept's successor). Robert has been strongly advocating the use of Boost.Concept, and I completely hear his rationale. As I understand, Robert's advocacy for Boost.Concept is that despite its shortcomings, it's currently available and works within its limitations. Are there fundamental objections to this approach -- such that if a new Concepts/ TypeRequirements library was available tomorrow which alleviated the problems in Boost.Concept -- there wouldn't be any objections to expecting its use? I've been following this thread for a while, and thought I'd offer my own thoughts on the matter. Regards, Michael