Re: [boost] [convert] incomplete reference documentation

Subject: Re: [boost] [convert] incomplete reference documentation
From: Vicente BOTET (vicente.botet_at_[hidden])
Date: 2011-04-07 13:42:32

> Message du 07/04/11 11:38
> De : "Vladimir Batov" 
> A : boost_at_[hidden]
> Copie à : 
> Objet : Re: [boost] [convert] incomplete reference documentation
> 
> > ----- Original Message ----- 
> > From: "Vicente BOTET" 
> > ...
> > My concerns are more before the review than after.
> > If you want to facilitate the task of the reviewers, and
> > as the interface is not too big, I suggest you to document
> > it by directly with quickbook before the review until you are
> > able to have a correct reference documentation with doxygen.
> 
> I've uploaded 1.05 where I managed to get better Reference-related results. 
> Namely, convert and result classes are represented there. Still, it looks 
> ridiculously little -- 3 overloads of convert::from and 2 functions in 
> result. I am somewhat skeptical of the value it adds. The specialized 
> convertor implementations are still hidden as I consider those 
> implementation details and do not want users to see those.
> 

I can accept that you want to hide the converter class. But you need to state in the documentation that the result of the from operation is a implementation defined class which is convertible to Target and provide in addition other operations which must be stated explicitly. Otherwise how the user can know that the following is correct

using namespace boost::conversion::parameter;
direction dir = convert::from(str, up_dir)(throw_ = true); 

or

int i = convert::from(hex_str) >> std::hex;
string si = convert::from(i) 
>> std::showbase >> std::uppercase >> std::hex;

Best,
Vicente