Re: [boost] [serialization docs] Ping?

From: Robert Ramey (ramey_at_[hidden])
Date: 2005-09-22 18:02:03

David Abrahams wrote:
> "Robert Ramey" <ramey_at_[hidden]> writes:
>
>> In order of frequence of usage, I see the documents as being used
>> to describe how to:
>>
>> a) make one's types serializable. ("Archive Concepts" and
>> "Serializable Concept")
>>
>> b) use archives which are included. ("Archive Models")
>>
>> c) make one's own archive implementation leveraging on the code
>> included. ("Archive Concept" and "Archive Implementation")
>>
>> d) make one's own archive implementation from scratch.  No one has
>> ever attempted this.  ("Archive Concept")
>
> That's exactly right.
>
>> I realize you don't buy this
>
> ???
>
>> and expect to see information which is
>> included in "Archive Implementation" moved to "Archive Concepts".
>
> Certainly not, unless "Archive Implementation" contains requirements
> for archives. You haven't been very clear about whether it does or
> not, but I think your last statement is that it doesn't.
>
>> But in my view that muddles the whole functional organization which
>> I was so careful to preserve above.  Its been this way since the
>> beginning.
>>
>> What's changed is that the descriptions are couched
>> in terms of "Concept" and "valid expressions" rather than function
>> prototypes a before.  At this point part of the documentation
>> uses one approach and other parts use the other and this is
>> confusing.
>
> ?? Concepts aren't supposed to be documented in the same way as
> classes.  There's nothing confusing about that.
>
>> That's why I would like to go back to were we started and just
>> elmininate the terms "Concept"
>
> Terms?

term

>
>> which imply a method
>
> Method?

of documentation

>
>> which hasn't been used in a consistent and correct way throughout
>> the document.

>> I've also come to believe that the notion of "Semantics" is
>> quite subjective and needs to be thought through more.
>
> Ugh.

>> So that is the basis of my suggestion for roling things back
>> to the begining and just removing the word "Concept" as
>> its use isn't really correct in that context.

> Finally, and recently, it does seem correct, but the concepts are just
> a little too weak to be useful.  It needs to give some semantic
> guarantees.  Or, more accurately, you need an additional two-type
> concept that associates loading and saving archives with one another.

and its not that obvious to me how to do that. Especially on short notice
which is my view of we're dealing with here.

There is another concern that I have.  In spite of all of the above, the
part of the documentation which I think needs the most work is
"Archive Implementation".   This is fairly complicated undertaking.  I
do suspect that it will result in a refinement of "Archive Concept" as
this task progresses.

Robert Ramey