Re: [boost] [serialization] Doc problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-08 18:48:08

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

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

You just claimed above that an archive has to support both << and >>.
That's inconsistent with the idea that you can write an archive that
only supports input, for example.

> I guess one should really say there are two archive concepts.  A
> Saving Archive concept and a Loading Archive concept.  

Okay, maybe _the docs_ should really say that.

> I'm not sure
> if that's what you're getting at.  

What I'm really getting at is that concepts need to be documented
rigorously, and not sort of clearly enough that you can explain the
real requirements to someone in a mailing list posting after they've
told you that your first explanation doesn't seem to match up with
reality.

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

Well, it doesn't aid in understanding.

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

If you don't like multi-type concepts, then when you describe the
effects of deserialization you need to have defined some notion of
"compatible archive format" that allows you to guarantee the results
make sense.  You can't expect to serialize with a binary oarchive and
deserialize with an XML iarchive and get a sensible result.

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

Lots of things can seem logical and common sense to their author but
be logically vacuous and thus utterly useless to someone who doesn't
already understand what the author intends to say.

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

Right.  But the author of a piece of software is not in a very good
position to judge the comprehensibility and utility of its
documentation.  IMO you ought to recognize that and not be so quick to
argue with someone who is reporting that the docs are hard to use and
suggesting ways to improve them, especially when that person has been
through that cycle many times with his own users and learnt from his
mistakes.

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

So?  Formatting aside, I don't see your point.

If all that can be grouped as boost::whatever it can also be grouped as
boost::serialization::whatever.

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

I'm confused about how you could think I am suggesting "Implementing
this in one namespace."  What do I need to do to make myself clearer.

> Now your thinking (may I presume)  well use serialization::archive and 
> serialization::serialization (or something similar).  

Yes.  Why are you wasting your time with all the foregoing?

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

Are the archive classes useful without the stuff in the serialization
namespace?

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

Yep, you need to do the same reorganization for dynamic libraries even if you
don't auto-link.  Boost.Python had to do it.

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

What's a "header module?"

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

I have no idea what this was about anymore.

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

Well, I clearly wouldn't have posted it if I couldn't get it to fail.
Clearly none of those is using 2-phase lookup.
Did you look at 14.6.4 Dependent name resolution [temp.dep.res] in the
standard like I suggested, or use the Comeau online compiler?

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