[boost] [result_of] Documentation update for ticket 7753

Subject: [boost] [result_of] Documentation update for ticket 7753
From: Nathan Crookston (nathan.crookston_at_[hidden])
Date: 2013-06-20 01:59:37

Hi Daniel & all,

I'm updating the patch for ticket 7753 (
https://svn.boost.org/trac/boost/ticket/7753).    I've made the requested
changes to the patch, but I had a question on how to best explain which
macro to define if, for example, you want result_of to work with C++11
lambdas.  In the past, users with a pre-N3276 decltype have been advised to
just #define BOOST_RESULT_OF_USE_DECLTYPE, with the explanation that "it's
probably just going to work."  While that advice is true, there are cases
where this doesn't work; hence the addition of
BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK.

To explain why you'd define the FALLBACK macro over the USE_DECLTYPE macro,
I'm thinking of including a paragraph like the following.

"The question naturally arises on why have both
BOOST_RESULT_OF_USE_DECLTYPE and
BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK.  In many situations,
BOOST_RESULT_OF_USE_DECLTYPE will work well, even with pre-N3276 decltype.
However, there are cases where a post-N3276 decltype is required to
correctly deduce the return type of a functor.  If a translation unit
includes a functor whose return type is only deducible with TR1 or a
post-N3276 decltype, using result_of with, e.g. a C++11 lambda function,
will fail without BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK.  If the
macro BOOST_NO_CXX11_DECLTYPE_N3276 is defined and BOOST_NO_CXX11_DECLTYPE
is not defined when including result_of.hpp, defining
BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK is the safest option that
will allow you to deduce C++11 lambda return types."

My question is, am I over explaining it?  Of course, I'd rather have
BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK defined automatically for
compilers like VC10, g++4.5, etc., and include text like the following:

"If you rely on the result of calling a nullary functor to be void,
regardless of the actual return type, or if your code is not written to
handle cases other than BOOST_RESULT_OF_USE_TR1 and
BOOST_RESULT_OF_USE_DECLTYPE, you may wish to explicitly define one of
those symbols prior to including result_of."

Either way, comments welcome.

Thanks,
Nate