Re: [boost] Boost.Conversion review

Subject: Re: [boost] Boost.Conversion review
From: John Bytheway (jbytheway+boost_at_[hidden])
Date: 2011-08-16 17:17:25

This is not a review.  Just some comments on the docs.  I have other
issues with the design which I'll raise in another post.

The one long page of docs is a bit intimidating.  At least it should be
split into reference and non-reference, I think.

Overview
--------

- s/Tatget/Target/

- In this:

template < class Source >
convertible_from<From> implicitly(Source source)
{
  return convertible_from<Source>(source);
}

I guess you mean "convertible_from<Source>" as the return type?

- When first discussing the need for is_constructible and is_assignable
(under "Caveats"), could you mention that there is a list of supported
compilers just below (to avoid scaring away people who don't know
whether their compiler is supported)?

User's Guide
------------

- You say it needs "compilers supporting decltype" -- would typeof
suffice also?

- "When you need to make a extrinsic explicit conversion" is ambiguous;
I suggest "When you need to perform an extrinsic explicit conversion".

- In "they can try with the make assigner to `lvalue' free function" you
have bold 'm', 'a', 't'; is this because the function used to be called
"mat"?  If so, they should probably be un-bolded.

- "Why ADLIt would be great if" looks like a mistake.

- In this:

template <typename T>
typename enable_if<is_extrinsically_convertible<int>,void >::type
f(T v) { return convert_to<int>(v); }

surely you need to pass T to is_extrinsically_convertible?

- Does is_extrinsically_convertible test for explicit or implicit
convertibility?  Is there a trait for the other one?

- I presume s/implicit_convert_cp/implicit_converter_cp/

- What does the "cp" signify?  I figured it out eventually but you
probably want to say.

- I assume there is also explicit_converter_cp and an
implicit_convert_to function you can overload with dummy_type?  You
should probably at least mention them in passing when introducing
implicit_converter_cp and explicit_convert_to.

Reference
---------

- The docs of BOOST_CONVERSION_NO_IS_ASSIGNABLE say "Macro stating if
the compiler doesn't support...".  Please clarify in what way the macro
"states" this; I think you mean "Macro defined if the compiler doesn't
support..." (and personally I would prefer "Macro defined if and only if
the compiler doesn't support...").  The other macros similarly.

- Please normalise the names of
BOOST_CONVERSION_NO_IS_EXPLICIT_CONVERTIBLE and
is_explicitly_convertible; the former should have the "LY".  Similarly
BOOST_CONVERSION_NO_IS_EXTRINSIC_ASSIGNABLE,
BOOST_CONVERSION_NO_IS_EXTRINSIC_CONVERTIBLE.

- You list all these headers providing specializations for standard
types, such as "Type traits specializations for <string> types." but
it's far from clear what these mean.  There are more details lower down,
but you wouldn't know that from looking at the short version.  Can you
point or link to the further details?

- "implicit conversion of the @ Source" -- I guess the @ is a typo?

- "Defines the free function assignable_to class" -- is it a function or
a class?

- ExtrinsicallyExplicitConvertible should probably be
ExtrinsicallyExplicitlyConvertible for consistency.

- boost/conversion/convertible_from.hpp is documented as "Defines the
free function implicitly.".  I have two problems with this: Surely it's
more significant that it defines convertible_from?  Also, I think
implicitly warrants its own header; I'm unlikely to remember that this
is what one must include to get it.

- What are the semantics for the conversions to/from std::string?

- Do the fusion::tuple conversions really only go up to 3-tuples?  What
about 1-tuples?

- Must all the "trick_*" classes really appear in the docs?

John Bytheway