Re: [boost] [serialization] Doc problems

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

"Robert Ramey" <ramey_at_[hidden]> writes:

> The library is two parts:
>
> a) Serialization Concept.  This describes what a type has to support
> in order to be considered a serializable type.  All the support for
> this concept is in the namespace "boost::serialization".  Its
> concievable that someday someone (not me) might want to expand this
> to something more grandios such as Reflection concept.  There is
> already a baby step in that direction wiht the notion of
> serializable traits, assignment of an exportable name, assignmetn of
> a printable name for the variable which the type is applied
> to(name-value pairs).  There is to be no notion of the archive
> concept here.
>
> b) Archive Concept.  This describes what an type has to support in order to 
> be used an archive.  Basically these requirements boil down to the archive 
> supporting the operations ar << and ar >> for any type which models the 
> Serialization Concept.

You mean the "Serializeable" Concept?  I thought input and output
archives could be different types?  Seems to me that you have a
multi-type concept (look that up in the indiana concepts proposal
cited earlier) at play here, 

      Serlializeable<InputArchive, OutputArchive, Datum>

with requirements, (given InputArchive ia, OutputArchive io, and Datum
d), something like:

  +----------------+----------+-----------------------------------------------+
  |Valid Expression|Semantics |Notes                                          |
  +================+==========+===============================================+
  |oa << d;        |d2 is     |I know, it's a bit more complicated than this  |
  |                |equivalent|since d may not be default constructible and   |
  |Datum d2;       |to d      |instead might support inplace deserializing.   |
  |                |          |Maybe there are two concepts for the two cases.|
  |ia >> d2;       |          |                                               |
  +----------------+----------+-----------------------------------------------+

> Thus
>
> a) any class fullfilling the requirements of the Archive Concept, can be 
> used to serialize any types which model the Serializable concept.

It's not a very useful concept unless it also allows you to
deserialize and be assured of a sensible result.

> b) in creating a new data type, it is sufficient to know that it
> fullfills the Serialization Concept to know that it can be
> serialized with any archive class.
>
> This is THE key design goal of the serialization libary.

That's great.  You have separation of concerns and orthogonality.  You
have turned an NxM problem into an N+M problem, just as iterators do
in the STL.  That doesn't mean the STL containers and algorithms
should all be in separate top-level namespaces!

> In fact, along with two requests for more formal documentation (one
> from you), one of my main motivations for investing effort in
> improving the documentation was to make this design much more
> obvious.  Hmmm - looks like it failed in this regard.  Oh well.
>
> My intention has been to organize source code modules in
> subdirectories and matching namespaces to reflect this design.  This
> is described in a special section of the manual.  

Makes sense, but it's all part of the serialization library.  Any
subnamespaces should go under boost::serialization.

> The maintainence of the key distinction between serialization and
> archive concepts - and the fact that perhaps its not as clear in the
> documentation as it might be has a couple of other repercussions
> that have manifested themselves on this list.
>
> a) Any header from the "serialization" part can be included in a header 
> without triggering requiremetn for the library even in the presense of 
> auto-link.  

I don't know what that means.  All I know is that you've had some
problems apparently related to auto-link.

> This would not have been possible without a library design based on
> this concept.  Actually supporting this was a some effort - mainly
> to fix places where I accidently violated this design feature.
>
> b) My imposition of the "rule" that serialiation headers precede
> archive headers.  This came about as an afterthought while fixeing
> the auto-link issue described above.  Remember I always have in mind
> that serialization is an independent concept an archives are
> dependent upon seerialization.  So it never occured to me that one
> would ever mix and archive and serialization header in another
> header.  So I saw no issue in imposing this "rule".  As it turned
> out, this "rule" wasn't really the the right way to fix the
> auto-link issue above and now I'm manage to fix it so the rule isn't
> necessary anymore.  But I'm struck by the fact that lots of people
> never saw my point of view.

Which point of view?

> c) I sometimes get code which overides the serialization for a
> specific archive.  I can see where sometimes it might be interesting
> (eg. a special archive type for debug or checkpointing) but in the
> cases I've seen its just done without considering that one is now
> breaking the orthogonality between archves and serializations in a
> way that doesn't add anything other than future job security.  Its
> not a big thing - its just slightly irksome - like sitting on a
> small pebble.

Sounds like, if you want to support that need while preserving
orthogonality, you need an additional layer of indirection in the
library design.

> Clearly there's an aspect of the library that I see as fundamental that 
> either I'm wrong about or have failed to communicate.  

Probably the latter.  How about making it more prominent in the docs?

> Oh well.
>
>>   if they were in  boost::serialization *and* users were required to 
>> derive from one
>>   of the archive types, that would solve problem 4.
>
> I believe that problem 4 is not a  problem.  Feel free to prove me wrong 
> here.

Already done, if you had only tried to compile the code I posted ;-)

> I very much appreciate you're looking at my documentation with your
> incredibly acute vision.  

You're welcome.  I had help from colleagues and clients, I admit.
Sometimes it's just a matter of being willing to write down what we've
noticed, and then go through the arguments that almost invariably
ensue.

> This is the first time anyone has really done this and find it very
> helpful.  I have spent more time on this than it might seem from
> looking at it and I do want to improve it - but it ain't as easy as
> it looks.

It never is.  Docs are hard and time-consuming to get right.  It helps
to encourage your critical reviewers :)

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