"Robert Ramey" <ramey@rrsd.com> 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