At Friday 2004-10-29 21:30, you wrote:
--- Robert Ramey <ramey@rrsd.com> wrote:
This was brought up some time ago. My response was that the
serialization library was used by overriding default behavior
implemented in base classes so there was no "list" of API calls. I
was directed to the documentation for new iterators which works the
same way. From this was born the
section:
Reference/Achive Class Reference/Implementation which I believe
contains the information you are requesting.
Before commenting on this I should say that I do understand that your time is limited and that other stuff might currently be more important than writing documentation. Moreover, I know from personal experience that writing standard style reference documentation is tedious and relatively unrewarding because users always measure docs by the tutorial. However, in every-day use in non-toy projects, formal descriptions of all concepts (see <http://www.boost.org/more/generic_programming.html#concept>),
classes and functions is IMHO essential.
When a particular function call does not do what you want (does not compile, fails with an exception, does the wrong thing, does nothing,
etc.) you'd want to know what the exact requirements for and effects of that function are. I agree that most of that information can currently be found in the serialization docs but it is almost always not in one place but spread out in several unrelated and unlinked locations.
The docs you mention are a start, but they are nowhere near complete.
A few examples:
- None of the function descriptions mentions exceptions that might be thrown.
- Few of the functions mention the requirements (preconditions) imposed on their arguments.
- There is no concept documentation on what requirements a type must satisfy in order to be saveable and/or loadable. Again, most of this information is there, it is just spread over too many places.
Here's an example of a good documentation of a normal class:
<http://www.boost.org/libs/thread/doc/condition.html#class-condition>
Here's a good example of concept documentation (these were probably the docs other people were referring to):
<http://www.boost.org/libs/iterator/doc/new-iter-concepts.html#iterator-trav ersal-concepts-lib-iterator-traversal>
I'm glad someone things that page is worthwhile. It (and the ones like it) are absolutely inscrutable to someone who hasn't had formal training in whatever they're trying to show.
Again, I understand that you might have other priorities right now, but in the long run I believe such reference docs should be part of every boost library (most have such docs), especially the ones that are candidates for standardization.
Regards,
Andreas
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Victor A. Wagner Jr. http://rudbek.com The five most dangerous words in the English language: "There oughta be a law"