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

From: Victor A. Wagner Jr. (vawjr_at_[hidden])
Date: 2004-10-30 01:08:13

At Friday 2004-10-29 21:30, you wrote:
>--- 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>

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"