[boost] Re: [serialization] Plans for C++ standard style reference docs

From: Robert Ramey (ramey_at_[hidden])
Date: 2004-10-29 23:30:21

--- Robert Ramey <ramey_at_[hidden]> 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>

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