Re: [boost] [serialization] Doc problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-04 18:41:18

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

> David Abrahams wrote:
>
>
> I've gone back and looked at this again.
>
>> 5. Archive Concept Requirements are specified in a completely new,
>>   unprecedented way.  I can see why you want to write them this way,
>>   but the result is that it isn't completely clear which elements of
>>   the interface are required and which are optional.
>
> The goal is to describe those functions that a class must implement to 
> function in order to guarentee that it will compile and execute with any 
> serializable type.
>
> If it fails to fullfill one or more requirements, it might work with some 
> serializable type - but there is no guarentee that it will compile with all 
> of them.

As I said, I understand the general intent.  It's the specific meaning
that's unclear.  It's especally unclear because you say "must
implement the following interface..." and then show one member
function with an implementation.  You could provide that
implementation by using a CRTP base class.

> Note that his concept is different than others in the standard library in 
> that one of the requirements is that it be  a class with certain required 
> member functions.  
>
> Most or all other concept definitions only specify 
> operations for which the type is valid. As far as I know this doesn't 
> include supporting specific member functions.

Actually, no.  All of the concepts in the Container hierarchy share
that property.

> The iterator library does require that an iterator be derived from a 
> specific class and permit that functions be overloaded

Hidden, actually.

> its sort of similar to what we have here - but I couldn't see an
> exact match.

Well, CRTP might be a good option for you, especially considering that
function implementation I mentioned in the first paragraph above.

> For example,
>>   there's a colon after the class name.
>
> class iarchive : ..
> {
> };
>
> is intended to illustrate that fact that an archive may be derived
> from somethng else but that this would be optional and that it is
> not a relevant feature of the archive concept.  Perhaps the :... is
> confusing and should be removed.

Sounds right to me.

>>  Does the class need to be derived from something?
>
> The concept requirements don't require or prohibit it.  It would be
> considered a feature of a specific model on the concept.  It didn't
> occur to me to be specific about this.

You don't need to be specific if there are well-defined rules for
reading your inteface prototype.  See pseudosignatures referenced in
my other email.

>>   What about the names of function and   member template parameters?
>>   I know the answer to that one, but a   novice might not.
> Hmmm - the only template parameters are flagged as
>
> template<class T>
>
> and the first sentence before they are used states
>
> "The template parameter T must correspond to a type which models the 
> Serializable concept"
>
> and the link points to documentation on the Serializable concept.
>
> So, I don't think I understand the question. (Uh oh, maybe I'm a novice too! 
> I often feel like here)

I mean, are users required to use the same function and template
parameter names as you are using in your interface prototype?  As I
said, I know the answer, but novices might not know it?

>>  What about the default arguments to member functions?  Is it okay to 
>> write overloads?
>
> What about them?  The concept describes necessary and sufficient conditions. 
> It doesn't prohibit anyone adding there own parameters as long as they are 
> optional so the concept interface is supported.  I don't think I really 
> understand this question.

The interface described by

     f(int x, int y = 1);

can nearly always be satisfied by overloads:

     f(int x, int y);
     f(int x);  // implementation would probably be { f(x,1); }

unless you take the address of f, for example.

So the question is, does the user actually need to use default
arguments where your interface description does, or would overloads
work just as well?  Since you don't have a description of how to
interpret your prototype, the answer is unclear.

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