[Boost-users] [serialization] installed documentation bug and suggestions.

Subject: [Boost-users] [serialization] installed documentation bug and suggestions.
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2010-03-13 19:19:56

Bugs:

I've had bad internet connection so I had to resort to using the installed  
boost docs and noticed some bugs.

1) /share/doc/boost/libs/serialization/doc/index.html   has broken links  
in the left frame.
2) /share/doc/boost/libs/serialization/doc/archive_reference.html has  
broken links in the following paragraph:

//Start
As a convenience, small header files have been included which contain  
typedef for polymorphic implementation for each corresponding templated  
one. For example, the headers polymorphic_text_iarchive.hpp and  
polymorphic_text_oarchive.hpp. contain the typedef for the polymorphic  
implementation of the standard text archive classes text_iarchive.hpp and  
text_oarchive.hpp respectively. All included polymorphic archives use the  
same naming scheme.
//End

Suggestion:

1) It's not readily apparent that there's a polymorphic implementation of  
the serialization classes, may be this should be mentioned in the tutorial?
2) Or have a section in the Overview page categorizing the available  
categories of serializors as intrusive, non-intrusive, polymorphic, giving  
a short definition of each type, and their pros/cons.

Basically what is missing is an eye-ball summary of the available  
serializors that this library offers, and why one would choose one over  
the other and vice versa.  The information is there, but it is scattered  
and it took some digging to get to it.  For example, from the overview  
page one cannot deduce that there exists an intrusive, or polymorphic  
version.  It is only from Tutorials page can one immediately deduce that  
there is an intrusive version, and to figure out there is a polymorphic  
version one has to navigate the following path: Reference link in left  
frame -> Archive Class Reference.

Also, best practices/potential pitfalls like the following suggestion:

//Start
//  
/share/doc/boost/libs/serialization/doc/tutorial.html#nonintrusiveversion
Note the serialization of the base classes from the derived class. Do NOT  
directly call the base class serialize functions. Doing so might seem to  
work but will bypass the code that tracks instances written to storage to  
eliminate redundancies. It will also bypass the writing of class version  
information into the archive. For this reason, it is advisable to always  
make member serialize functions private.
//End

should be made more eye grabbing.  It's very easy to accidentally skip  
over such information.

Thanks,

- Mostafa