[boost] [serialization] Doc problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-04 03:54:12

Hi Robert and Jonathan,

In preparing some slides for a course I'm giving, I've been reading
through the serialization documentation.  Although it's generally well
organized and presented, there are a few problems:

1. The menu control doesn't seem to keep the browser's displayed URL
   in synch with the location being browsed (FireFox on Windows XP).
   Wasn't that a major coup of Jonathan's menu control?

2. Deserialization of derived classes through base class pointers is
   an incredibly important subject -- even for many first-time users
   -- but the instructions for handling it are buried deep in 
   Reference > Serializable Concept > Pointers > Pointers to Objects
   of Derived Classes
   (http://www.boost.org/libs/serialization/doc/serialization.html#derivedpointers)
   
   This material _needs_ to be in the tutorial!  In fact, the material
   in the reference section is narrative and tutorial in nature, which
   seems inappropriate for a reference manual.  Maybe you should just
   move it?

3. In that reference section, '&' is used repeatedly where only '>>'
   is appropriate.  For example:

     main(){
        ...
        base *b;
        ar & b; 
     }
     
   That can only be confusing.

4. The documentation says that you can write your freestanding
   serialize() function in namespace boost::serialization, with the
   strong implication that it will work even on compilers that support
   ADL.  But it won't work unless boost::serialization is an
   associated namespace of one of the arguments, as demonstrated by
   the following program:

        namespace me
        {
          class X {};
        }

        namespace boost { namespace serialization
        {

          template <class T>
          int call_serialize(T const& x)
          {
             serialize(x);
             return 0;
          }

          void serialize(me::X);

        }}

        int y = boost::serialization::call_serialize(me::X());

   As far as I can tell, there's no requirement that any of the
   arguments to serialize have boost::serialization as an associated
   namespace.

5. Archive Concept Requirements are specified in a completely new,
   unprecedented way.  I can see why you want to write them this way,
   but the result is that it isn't completely clear which elements of
   the interface are required and which are optional.  For example,
   there's a colon after the class name.  Does the class need to be
   derived from something?  What about the names of function and
   member template parameters? I know the answer to that one, but a
   novice might not.  What about the default arguments to member
   functions?  Is it okay to write overloads?

   Also, there's an extra pair of namespace closers in the second
   archive concept example.
   
6. In
   http://www.boost.org/libs/serialization/doc/archive_reference.html#implementation
   it says:

        All input archives should be derived from the following
        template:

          template<class Archive>
          detail::common_iarchive;
   
   but that's nowhere to be found in the archive concept requirements.
   Which is it?  Also, that "detail::" is actually nested in the
   boost::archive namespace, which is not at all clear from the text
   there.  It's not clear to me why archives should live in a
   namespace other than serialization; if they were in
   boost::serialization *and* users were required to derive from one
   of the archive types, that would solve problem 4.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com