Michael Levine wrote
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?
indeed. This is a key part of the documentation. It's also one of the more difficult to make general statements about. For this reason, although I've tried to make recommendations about this aspect, I'm not making a big deal about this. I've been focusing on the reference part of the documentation because it's an easier sell. Once we can sell this, the rest will be easier. Basically my suggestion would be: a) intro - purpose of the library with motivating examples. b) more examples and advice on library usage c) rationale - why things were done the way they were and not some other way d) reference e) acknowledgements. But as I said - this is not (yet) part of the current crusade.
I completely understand the extreme difficulty involved in trying to enforce a specific style and format of the documentation on the library authors.
I've been trying to make my case in regards to content and it's organization. I've consciously tried to avoid specifying style, format, tools etc. We have excellent examples of documentation made with the simplest of tools - see iterators - and very hard to use documentation made with the latest/great tools - see boost units. www.blincubator.com explicitly makes the case in documentation requirements and format, tools, etc is discussed in a totally different section - simple tools.
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.
I've taken great pains to address this - see above.
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.
Hallelujah!!!
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).
It seems that "concepts lite" is shaping up to be the next episode in an on going ten year saga. For me it makes no difference. If it ever makes it and people want to use it - fine. I even provide a table for translating boost concept classes into concepts lite code. But this is not really relevant to my argument. Basically the whole concepts discussion/development has been blown way out of proportion: a) the important thing is that library which use parameterized types need a method of specify and enforcing requirements on those types. boost concept works for this concepts lite will work for this and in fact just inserting some static asserts can work just as well for this. (I'll be updating www.blincubator.com to demonstrate this). b) very few C++ programmer right now code with parameterized types. c) even fewer publish such code. d) even fewer explicitly specify parameter type requirements. e) and even fewer actually include code to detect violations. So it's beyond me that is an issue which requires some sort of enhancement to C++ (concepts lite). I'm sure that 1/10 the amount of time disputing concepts would have been more than sufficient to specify and enforce type requirements in all the boost libraries. Just to make myself clear - the path to better library code is for library authors to specify and verify concepts - and we already have all we need to do that. If the committee want's to spend more time on this - fine - but it won't make any difference unless library writers change their habits.
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 wouldn't have any objections. I'm curious that no one has called for compiler changes to require type requirements on template parameters - as they are not for non-template parameters. It's odd to me that this hasn't come up (to my knowledge). Not that I'm convinced this would be a good idea. But think about it. I doubt anyone objects to the requirement that functions specify the types of their (non-template) arguments. And it wasn't always so - when I started with C - function arguments types could be omitted - in which case they defaulted to int. This caused a lot of pain - not all that unlike the pain that undefined template type requirements cause to day.
I've been following this thread for a while, and thought I'd offer my own thoughts on the matter.
Happy to hear from you - I can always use another opportunity to flog my case. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Concepts-Definition-Was-GSoC-Boost-Hana-F... Sent from the Boost - Dev mailing list archive at Nabble.com.