Re: [boost] [serialization] Doc problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-09 17:59:02

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

> It's become clear to me that users of the serialization library are
> of at least two kinds.
>
> a) those who use archives included with the system.
>
> This would be analgous to a user of say a transform_iterator who no
> interest about how its constructed but just wants to use it.  He
> doesn't need to know how its implemented.

No user should be interested in how transform_iterator is constructed
except as an instructive example.  In the domain where concepts are
useful, instructive examples are icing on the cake, but not crucial.
I'm not asking for anything analogous to details about how
transform_iterator is implemented, and I don't care how the
library-supplied archives are implemented.

> He just needs to know the requirements on its type arguments and the
> operations it supports.  This is the intent of the Archive Concept
> section and I believe that it fullfills this role.

Then you should rename that section.  Concepts are not for describing
the commonalities of a few components provided by a library (standard
container requirements notwithstanding); they're for describing the
minimal _requirements_ of other library components: the ones to which
models of the concepts are passed. In your case, that means the
archive concepts should describe the requirements of the serialization
code to which archives are passed.  I know you like to think of the
archive concept and the serialization library as somehow independent,
but that just doesn't reflect reality: serialization makes certain
assumptions about the objects passed to it as archives and those
assumptions need to be spelled out if there are ever going to be any
archives other than the ones you wrote.

> I see no problem in refining it along the lines of this recent
> discussion.  I might note that no one up to now seems to have had
> too much difficulty in using the library at this level, so although
> I don't mind making the changes, I don't think its going to affect
> things very much in the scheme of things.  

What is your point?  That the documentation is really okay the way it
is?

> Of course, it might be that not that many people use the package at
> all and that's the reason I don't get complaints on this.  Its very
> hard to know.

If you don't care about making a Generic C++ Library -- in the Generic
Programming sense as the discipline was developed by Stepanov and
Musser and carried through into the STL and the BGL, etc. -- that's
fine, although it would be a terrible missed opportunity.  But then
you shouldn't be using terms like "concept" in the context of Boost
and C++ where it has a very specific meaning, and raises the
expectations of your users that they'll be able to create new
components that work with your library.

> b) those who wish to make thier own archive.
>
> This is different and much smaller group of users. 

So?

> It would be analogous to those how want to make new iterator using
> the facilities of the new iterator library.  This requires much more
> than than just type requirements of some of the classes.

No.

> I made a family of dataflow iterators so I know first hand about
> this.  

I don't know what you mean by that, but if you tried to use the
iterator library to build a new iterator and the library's
requirements tables didn't tell you what you needed to know, then it
was either an outright bug in the library docs or you didn't
understand how to read them properly.

> This is the intent of the section "Archive Implementation".
> Having a clearer idea of the role of this part of the documentation
> will permit me to improve this as well.  One could say "Given a
> clear and unambigous Archive Concept", design of a particular model
> (archive class) is an implementation detail.  

An implementation detail of what?  I don't know what that means.  If
you replace "an implementation detail" by "possible," then it makes
sense to me.

> And for most users it is.  But for users wanting to make their own
> archive, I want to better describe how to use the included classes.

I don't see how understanding how to use the included classes is going
to help me satisfy the requirements of the serialization library when
I need to build a new archive.

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