[Boost-commit] svn:boost r78603 - in sandbox/type_erasure/libs/type_erasure: doc example

Subject: [Boost-commit] svn:boost r78603 - in sandbox/type_erasure/libs/type_erasure: doc example
From: steven_at_[hidden]
Date: 2012-05-24 16:18:22

Author: steven_watanabe
Date: 2012-05-24 16:18:21 EDT (Thu, 24 May 2012)
New Revision: 78603
URL: http://svn.boost.org/trac/boost/changeset/78603

Log:
Doc tweaks.
Text files modified: 
   sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk |    23 +++++++++++++++++++++--                 
   sandbox/type_erasure/libs/type_erasure/example/custom.cpp   |     9 +++++++++                               
   sandbox/type_erasure/libs/type_erasure/example/multi.cpp    |     2 +-                                      
   sandbox/type_erasure/libs/type_erasure/example/overload.cpp |     5 ++++-                                   
   4 files changed, 35 insertions(+), 4 deletions(-)

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	2012-05-24 16:18:21 EDT (Thu, 24 May 2012)
@@ -327,6 +327,12 @@
 
 [section:design Design Notes]
 
+This section is purely for informational
+purposes.  You don't need to read it to
+understand how to use the library.  Here,
+I try to explain how the library evolved
+and why I chose the current interfaces.
+
 [section:concepts Concept Interfaces]
 
 When designing the concept system, I had a couple
@@ -386,7 +392,7 @@
 type using an existing set of bindings.  This
 is what happens for the copy constructor.  The
 last kind of constructor "upcasts" from one
-concept to another more general more general
+concept to another more general
 concept.  For example, `any< mpl::vector<copy_constructible<>, incrementable<> > >`
 should be convertible to `any<copy_constructible<> >`.
 We want to define these three kinds of constructors
@@ -500,6 +506,19 @@
 
 [endsect]
 
+[section:placeholder Placeholder Names]
+
+An earlier version of the library used the names `_1`, `_2`, etc.
+instead of `_a`, `_b`, etc.  This caused a certain amount
+of confusion because the numbered placeholders are
+already used by several other libraries including
+Boost/Std Bind, Boost.Phoenix, and Boost.MPL.  I
+eventually decided that since the placeholders represented
+named parameters instead of positional parameters,
+letters were more appropriate than numbers.
+
+[endsect]
+
 [endsect]
 
 [section:feedback Feedback Wanted]
@@ -542,7 +561,7 @@
   happy about having it in `Concept` either, but
   I'm not sure where else it could go.  It's presence
   can affect the contents of the vtable, so if it
-  we're a separate template argument, it would have
+  were a separate template argument, it would have
   to be passed to __binding as well.  It would generally
   add complication.
 

Modified: sandbox/type_erasure/libs/type_erasure/example/custom.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/custom.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/custom.cpp	2012-05-24 16:18:21 EDT (Thu, 24 May 2012)
@@ -35,6 +35,15 @@
 /*`
     This works, but we'd really like to call `c.push_back(10)`.
     We can add members to __any by specializing __concept_interface.
+    The first argument is `push_back`, since we want to inject a member
+    into every __any that uses the `push_back` concept.  The second argument,
+    Base, is used by the library to chain multiple uses of __concept_interface
+    together.  We have to inherit from it publicly.  Other than
+    that we can ignore it.  The third argument is the placeholder
+    that represents this any.  If someone used `push_back<_c, _b>`,
+    we only want to insert a `push_back` member in the container,
+    not the value type.  Thus, the third argument is the container
+    placeholder.
 */
 namespace boost {
 namespace type_erasure {

Modified: sandbox/type_erasure/libs/type_erasure/example/multi.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/multi.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/multi.cpp	2012-05-24 16:18:21 EDT (Thu, 24 May 2012)
@@ -39,7 +39,7 @@
     any_type z(x + y);
     std::cout << z << std::endl; // prints 17
     /*`
-        The types of the arguments must match or the
+        The underlying types of the arguments of `+` must match or the
         behavior is undefined.
     */
     //]

Modified: sandbox/type_erasure/libs/type_erasure/example/overload.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/overload.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/overload.cpp	2012-05-24 16:18:21 EDT (Thu, 24 May 2012)
@@ -80,7 +80,10 @@
 
 /*`
     This uses SFINAE to detect whether a using declaration is
-    needed.  Another solution to the problem that I've used
+    needed.  Note that the fourth argument of __concept_interface
+    is a dummy parameter which is always void and is
+    intended to be used for SFINAE.
+    Another solution to the problem that I've used
     in the past is to inject a dummy declaration of `fun`
     and always put in a using declaration.  This is an
     inferior solution for several reasons.  It requires an