Paul Mensonides wrote: [...] I like what you wrote here:
Any given interface falls at some point between completely specific to completely general. An interface that is completely specific has only one specific use case. Such an interface is not a _library_ interface. An interface that is completely general has an infinite set of use cases that covers an infinitely broad scope. Such an interface cannot exist. Libraries in Boost vary greatly in where they fall along this specific->general axis.
I may have used the words concrete->abstract axis. It might be a basis on which to rate the libraries with a "fuzzy" classification that indicates position on the axis and spread of coverage. E.g. Boost.Crc even contains some pre-defined ready-to-use concrete types, whereas at the other extreme Boost.MPL is an abstract framework.
The more general a library is, the more difficult it is to describe the library in terms of use cases. When a library approaches being completely general, effective use requires a significant amount of lateral thought by the user, not use cases in the documentation.
From a purely practical POV here is the communications problem: I have a piece of software to construct and I have sufficient confidence that I can write it in C/C++ in N weeks from the ground up. How can I extract enough information from the Boost docs to identify those Boost libs that are applicable to my problem domain? How can I then evaluate those libraries so identified, enough to be convinced that the full *learning* time plus deployment time will result in the project lasting N weeks or less? And so it goes on with quality issues etc...
Examples (as opposed to use cases) in the documentation exist mainly as an attempt to induce the necessary lateral thought, not to show what problems the library solves.
Examples - yes, I can't get enough of them. A couple of small caveats: a) There is a danger that you might not relate to an example if you can't see that by changing a few things you can put it to good use in your particular context. OK so you can't please all of the people all of the time. b) Examples need to be grounded in the real world - which tenuously links to use cases. 'foo/bar' examples should be banned :-)
Hopefully, that made any kind of sense.
A great deal. Thanks Jim