|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r83334 - in sandbox/type_erasure: boost/type_erasure libs/type_erasure/doc
From: steven_at_[hidden]
Date: 2013-03-06 15:59:58
Author: steven_watanabe
Date: 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
New Revision: 83334
URL: http://svn.boost.org/trac/boost/changeset/83334
Log:
Doc update.
Text files modified:
sandbox/type_erasure/boost/type_erasure/any.hpp | 48 ++++++++++++++++++++++++++++++---------
sandbox/type_erasure/boost/type_erasure/param.hpp | 2
sandbox/type_erasure/boost/type_erasure/tuple.hpp | 9 ++++---
sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam | 3 ++
sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk | 11 ++++++++
5 files changed, 56 insertions(+), 17 deletions(-)
Modified: sandbox/type_erasure/boost/type_erasure/any.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/any.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/any.hpp 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
@@ -118,12 +118,14 @@
/**
* The class template @ref any can store any object that
- * models a specific @c Concept. It dispatches all
- * the functions defined by the @c Concept to the contained type
+ * models a specific \Concept. It dispatches all
+ * the functions defined by the \Concept to the contained type
* at runtime.
*
- * \tparam Concept The concept that the type should model.
+ * \tparam Concept The \Concept that the stored type should model.
* \tparam T A @ref placeholder specifying which type this is.
+ *
+ * \see concept_of, placeholder_of, \any_cast, \is_empty, \binding_of, \typeid_of
*/
template<class Concept, class T = _self>
class any :
@@ -150,11 +152,23 @@
{}
#endif
/**
- * Constructs a null @ref any.
+ * Constructs an empty @ref any.
+ *
+ * Except as otherwise noted, all operations on an
+ * empty @ref any result in a @ref bad_function_call exception.
+ * The copy-constructor of an empty @ref any creates another
+ * null @ref any. The destructor of an empty @ref any is a no-op.
+ * Comparison operators treat all empty @ref any "anys" as equal.
+ * \typeid_of applied to an empty @ref any returns @c typeid(void).
+ *
+ * An @ref any which does not include @ref relaxed in its
+ * \Concept can never be null.
*
* \pre @ref relaxed must be in @c Concept.
*
* \throws Nothing.
+ *
+ * @see \is_empty
*/
any()
{
@@ -193,7 +207,7 @@
* The @c Concept will be instantiated with the
* placeholder @c T bound to U.
*
- * \param data The object to construct the @ref any from.
+ * \param data The object to store in the @ref any.
*
* \pre @c U is a model of @c Concept.
* \pre @c U must be \CopyConstructible.
@@ -201,6 +215,9 @@
*
* \throws std::bad_alloc or whatever that the copy
* constructor of @c U throws.
+ *
+ * \note This constructor never matches if the argument is
+ * an @ref any, @ref binding, or @ref static_binding.
*/
template<class U>
any(U&& data_arg)
@@ -216,8 +233,8 @@
* Constructs an @ref any to hold a copy of @c data
* with explicitly specified placeholder bindings.
*
- * \param data The object to construct the @ref any from.
- * \param binding Specifies the actual types that
+ * \param data The object to store in the @ref any.
+ * \param binding Specifies the types that
* all the placeholders should bind to.
*
* \pre @c U is a model of @c Concept.
@@ -228,6 +245,8 @@
*
* \throws std::bad_alloc or whatever that the copy
* constructor of @c U throws.
+ *
+ * \note This constructor never matches if the argument is an @ref any.
*/
template<class U, class Map>
any(U&& data_arg, const static_binding<Map>& binding_arg)
@@ -272,8 +291,8 @@
*
* \param other The object to make a copy of.
*
- * \pre @c Concept must contain @ref constructible<T(const T&)>.
- * (This is included in @ref copy_constructible<T>)
+ * \pre @c Concept must contain @ref constructible "constructible<T(const T&)>".
+ * (This is included in @ref copy_constructible "copy_constructible<T>")
*
* \throws std::bad_alloc or whatever that the copy
* constructor of the contained type throws.
@@ -361,6 +380,9 @@
*
* \throws std::bad_alloc or whatever that the copy
* constructor of the contained type throws.
+ *
+ * \warning This constructor is potentially dangerous, as it cannot
+ * check at compile time whether the arguments match.
*/
template<class Concept2, class Tag2>
any(const any<Concept2, Tag2>& other, const binding<Concept>& binding_arg)
@@ -382,7 +404,8 @@
*
* \param arg The arguments to be passed to the underlying constructor.
*
- * \pre @c Concept must contain a matching instance of @ref constructible.
+ * \pre @c Concept must contain an instance of @ref constructible which
+ * can be called with these arguments.
* \pre At least one of the arguments must by an @ref any with the
* same @c Concept as this.
* \pre The bindings of all the arguments that are @ref any's, must
@@ -390,6 +413,9 @@
*
* \throws std::bad_alloc or whatever that the
* constructor of the contained type throws.
+ *
+ * \note This constructor is never chosen if any other constructor
+ * can be called instead.
*/
template<class... U>
explicit any(U&&... arg);
@@ -972,7 +998,7 @@
return *this;
}
/**
- * \pre @c Concept includes @c destructible<T>.
+ * \pre @c Concept includes @ref destructible "destructible<T>".
*/
~any()
{
Modified: sandbox/type_erasure/boost/type_erasure/param.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/param.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/param.hpp 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
@@ -258,7 +258,7 @@
* \brief Metafunction that creates a @ref param.
*
* If @c T is a (cv/reference qualifed) placeholder,
- * returns @ref param<@ref concept_of "concept_of"<Any>::type, T>,
+ * returns @ref param<@ref concept_of "concept_of<Any>::type", T>,
* otherwise, returns T. This metafunction is intended
* to be used for function arguments in specializations of
* @ref concept_interface.
Modified: sandbox/type_erasure/boost/type_erasure/tuple.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/tuple.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/tuple.hpp 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
@@ -23,9 +23,10 @@
/**
* @ref tuple is a Boost.Fusion Random Access Sequence containing
- * @ref any "anys". Concept is interpreted in the same way as for
- * @ref any. The remaining arguments must be (possibly const
- * and/or reference qualified) placeholders.
+ * @ref any "anys". @c Concept specifies the \Concept for each
+ * of the elements. The remaining arguments must be (possibly const
+ * and/or reference qualified) placeholders, which are the
+ * @ref placeholder "placeholders" of the elements.
*/
template<class Concept, class... T>
class tuple
@@ -33,7 +34,7 @@
public:
/**
* Constructs a tuple. Each element of @c args will
- * be used to initialize the corresponding member.
+ * be used to initialize the corresponding @ref any member.
* The @ref binding for the tuple elements is determined
* by mapping the placeholders in @c T to the corresponding
* types in @c U.
Modified: sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam (original)
+++ sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
@@ -31,9 +31,12 @@
<doxygen:param>EXPAND_ONLY_PREDEF=YES
<doxygen:param>"ALIASES= \\
CopyConstructible=\"<a href=\\\"$(BOOST_ROOT)/doc/html/CopyConstructible.html\\\">CopyConstructible</a>\" \\
+ Concept=\"@xmlonly<link linkend=\\\"boost_typeerasure.conceptdef\\\">Concept</link>@endxmlonly\" \\
call=\"@xmlonly<functionname alt=\\\"boost::type_erasure::call\\\">call</functionname>@endxmlonly\" \\
any_cast=\"@xmlonly<functionname alt=\\\"boost::type_erasure::any_cast\\\">any_cast</functionname>@endxmlonly\" \\
typeid_of=\"@xmlonly<functionname alt=\\\"boost::type_erasure::typeid_of\\\">typeid_of</functionname>@endxmlonly\" \\
+ binding_of=\"@xmlonly<functionname alt=\\\"boost::type_erasure::binding_of\\\">binding_of</functionname>@endxmlonly\" \\
+ is_empty=\"@xmlonly<functionname alt=\\\"boost::type_erasure::is_empty\\\">is_empty</functionname>@endxmlonly\" \\
require_match=\"@xmlonly<functionname alt=\\\"boost::type_erasure::require_match\\\">require_match</functionname>@endxmlonly\" "
<doxygen:param>"PREDEFINED= \\
\"BOOST_TYPE_ERASURE_DOXYGEN=1\" \\
Modified: sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk (original)
+++ sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk 2013-03-06 15:59:57 EST (Wed, 06 Mar 2013)
@@ -212,13 +212,20 @@
[section:conceptdef Concept Definitions]
+A Concept defines a set of constraints on the types that
+are stored in an __any.
+
There are three kinds of concepts.
# The library defines a number of [link boost_typeerasure.predef predefined concepts].
+ Most of these are equivalent to user-defined concepts, but a few
+ require special handling.
+# Users can define their own primitive concepts as described below.
+ The macros __BOOST_TYPE_ERASURE_MEMBER and __BOOST_TYPE_ERASURE_FREE
+ define concepts of this form.
# Any MPL Forward Sequence whose elements are
concepts is also a concept. This allows concepts
to be composed easily.
-# Users can define their own primitive concepts.
Each primitive concept defines a single function.
A primitive concept must be a specialization of a
@@ -238,6 +245,8 @@
Any other placeholders are ignored.
+A concept is instantiated by constructing an
+__any from a raw value or by constructing a __binding.
When a concept is instantiated with a specific
set of type bindings, each placeholder is bound
to a cv-unqualified non-reference type. After
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk