Re: [boost] [serialization] Doc problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-06 08:10:30

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

> Thinking about this while I was trying to sleep my thoughts on this 
> clarified a little
>
> There are really two things going on here.
>
> a) There is a use using an archive.  

?? sorry, can't parse that.

> This is very similar to a user using a collection.  He needs a
> description of the user interface for the collection class.  This is
> essentially a list of requirements on the collection class template
> arguments and a list of member functions.  The achive classes have
> no template arguments so the archive concept description fills the
> role.  It is also very analogous to the standard class header.
>
> b) There are facilities for creating a new archive class.  These would be 
> most analogus to the boost iterator.  The archive classes use CRTP. 
> Actually this part has been considered an implementation detail given the 
> common interface to all archives described in the archive concept.  Hence 
> its not really described in the documentation at all.
>
> I suspect that part of any confusion is that one is expecting to find b) but 
> finds only a).
>
> If one is looking for a) then he never notices that b) isn't there.

We don't care about any of that.  All I -- and the people I'm working
with, who can't figure this out either -- care about are the minimal
requirements on a type in order for the serialization library to use
it as an archive.  *That* is the proper definition of the Archive
concept.

Let me add, if you haven't already got a lot of experience defining
concepts rigorously, this is a bad time to try to innovate by using a
pseudosignature approach.  Write requirements tables using the
standard columns, as applicable:

  valid expression
  result type requirements
  semantics
  preconditions/postconditions
  invariants
  notes

One of the best ways to make sure you have the right concept
specification is to use the Boost Concept Checking Library and define
a concept archetype, then throw it at your code.  That will at least
check that you've got all the syntactic requirements right.  Semantic
requirements, you need to think through on your own.

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