Re: [boost] [serialization] Doc problems

From: Robert Ramey (ramey_at_[hidden])
Date: 2005-09-05 00:07:50

David Abrahams wrote:
> "Robert Ramey" <ramey_at_[hidden]> writes:
>
>> The library is two parts:
>>
>> a) Serialization Concept.
...
>> 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?
Of course, sorry

> I thought input and output > archives could be different types?

I don't understand this. I guess one should really say there are two archive 
concepts.  A Saving Archive concept and a Loading Archive concept.     I'm 
not sure if that's what you're getting at.  But there it is.  They are noted 
as being different but explained in terms of just one of them in order to 
save typing and aid understanding through the usage of symetry and analogy.

Seems to me that you have a
> multi-type concept (look that up in the indiana concepts proposal
> cited earlier) at play here,
...

Well, just my opinion - this idea seems a lot more complicated to explain 
and understand.

>> 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.

Lots of things can be formally correct but utterly useless.  Or so it would 
seem.  I would suggest something like non-euclidean geometry.  But the real 
question is what is the proper role and purpose of formal documents?  If its 
to describe something in a mathematical sense you'll have one thing.  The 
other extreme would be a cookbook.  A software library is something in 
between.  We're trying to find where it fits.

> 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!

It doesn't mean they shouldn't either.  Some statistics on the serialization 
library

directory    lines of code    files
======    ========    ===
serialization    6600    46
archive    9400    89
src    3200    37
doc    7200    34
test    8400    105
example    2200    18
build    233    3
====    =======    ====
total    37200    326

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

This is a BIG package.  Its a huge job to keep things from getting mixed up. 
Implementing this in one namespace would have be a big problem.

Now your thinking (may I presume)  well use serialization::archive and 
serialization::serialization (or something similar).  I suppose this could 
have been done but it wouldn't have added anything other than a lot of 
typing.  The current organization makes it clear to me that serialization 
(ncluding serializaton class traits) is really a sort of reflection which 
says something about the class without regard to how any particular archive 
class chooses to render it.

>> 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.

suppose I have a header x.hpp which includes he auto link stuff.

class X {
    void f(); // declared - defined in library code
    void g(){ // declared and defined here.
        ...
    }
};

Now I make a program which uses x.hpp

#include "x.hpp"
int main(...
    X x;
    x.g();
}

Auto-link requires the library to be present and linked into the program in 
order to build.  This occurs even though there are no calls to any code in 
the library.  This is conflicts with common practice of declaring functions 
taht are not always used.  Avoiding this situation required some 
re-organization.

>> But I'm struck by the fact that lots of people
>> never saw my point of view.
>
> Which point of view?

That including archive headers and serialization headers in the same header 
module breaks the orthogonality between these concepts and that breaking 
orthogonality suggests a design error.

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

Its supported now - but not requried.  That seems to be in line with users 
needs and desires.

>> 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?

The docs are pretty careful about not mixing these things up.  I'll consider 
making an explicit statement regarding this.

>> 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 did - it compiles fine with VC 7.1, Commeau 4.3, Borland 5.64, and gcc 3.3

Robert Ramey