[serialization] Plans for C++ standard style reference docs
At the risk of asking something that has probably been asked before: Are there any plans to add C++ standard style reference documentation for serialization? The current tutorial & reference are good and probably describing most of what one would like to know about the library. However, at various places I would really have preferred a description of the exact effects of a particular function, complete with pre-/post-conditions and exceptions that could possibly be thrown. Regards, -- Andreas Huber When replying by private email, please remove the words spam and trap from the address shown in the header.
"Andreas Huber" <ahd6974-spamgroupstrap@yahoo.com> writes:
At the risk of asking something that has probably been asked before: Are there any plans to add C++ standard style reference documentation for serialization? The current tutorial & reference are good and probably describing most of what one would like to know about the library. However, at various places I would really have preferred a description of the exact effects of a particular function, complete with pre-/post-conditions and exceptions that could possibly be thrown.
If there aren't such plans, there ought to be. It's too bad, but libraries really need tutorial, reference, and implementation docs to be completely documented. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
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. Robert Ramey "Andreas Huber" <ahd6974-spamgroupstrap@yahoo.com> wrote in message news:clmgr3$uuv$1@sea.gmane.org...
At the risk of asking something that has probably been asked before: Are there any plans to add C++ standard style reference documentation for serialization? The current tutorial & reference are good and probably describing most of what one would like to know about the library. However, at various places I would really have preferred a description of the exact effects of a particular function, complete with pre-/post-conditions and exceptions that could possibly be thrown.
Regards,
-- Andreas Huber
--- 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> 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
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"
Victor A. Wagner Jr. wrote:
<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.
FWIW, when I first encountered such documentation it also struck me as rather odd. I think the reason was that I did not see what a concept is and why it is necessary. However, as soon as I understood that part (I don't think it is that difficult) I became to appreciate the precision and conciseness of such documentation. How else would you document the requirements on a type? Regards, -- Andreas Huber When replying by private email, please remove the words spam and trap from the address shown in the header.
Robert Ramey wrote:
Before commenting on this I should say that I do understand that your time [rest of post snipped]
This post is a copy of a private email I've sent to Robert. He posted that email to the list under his name. -- Andreas Huber When replying by private email, please remove the words spam and trap from the address shown in the header.
participants (4)
-
Andreas Huber -
David Abrahams -
Robert Ramey -
Victor A. Wagner Jr.