[Boost-commit] svn:boost r48345 - in trunk: boost/proto/transform libs/proto/doc

From: eric_at_[hidden]
Date: 2008-08-24 02:34:01

Author: eric_niebler
Date: 2008-08-24 02:34:00 EDT (Sun, 24 Aug 2008)
New Revision: 48345
URL: http://svn.boost.org/trac/boost/changeset/48345

Log:
more doxygen comments for some proto primitive transforms
Text files modified: 
   trunk/boost/proto/transform/arg.hpp |    91 ++++++++++++++++++++++++++++++++++----- 
   trunk/libs/proto/doc/protodoc.xml   |    54 +++++++++++++++++------                 
   2 files changed, 119 insertions(+), 26 deletions(-)

Modified: trunk/boost/proto/transform/arg.hpp
==============================================================================
--- trunk/boost/proto/transform/arg.hpp	(original)
+++ trunk/boost/proto/transform/arg.hpp	2008-08-24 02:34:00 EDT (Sun, 24 Aug 2008)
@@ -20,6 +20,14 @@
 
     /// \brief A PrimitiveTransform that returns the current expression
     /// unmodified
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// proto::terminal<int>::type & j = proto::_expr()(i);
+    /// assert( boost::addressof(i) == boost::addressof(j) );
+    /// \endcode
     struct _expr : transform<_expr>
     {
         template<typename Expr, typename State, typename Data>
@@ -27,7 +35,8 @@
         {
             typedef Expr result_type;
 
-            /// \param expr An expression
+            /// Returns the current expression.
+            /// \param expr The current expression.
             /// \return \c expr
             /// \throw nothrow
             typename impl::expr_param operator()(
@@ -43,6 +52,14 @@
 
     /// \brief A PrimitiveTransform that returns the current state
     /// unmodified
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// char ch = proto::_state()(i, 'a');
+    /// assert( ch == 'a' );
+    /// \endcode
     struct _state : transform<_state>
     {
         template<typename Expr, typename State, typename Data>
@@ -50,6 +67,7 @@
         {
             typedef State result_type;
 
+            /// Returns the current state.
             /// \param state The current state.
             /// \return \c state
             /// \throw nothrow
@@ -66,6 +84,15 @@
 
     /// \brief A PrimitiveTransform that returns the current data
     /// unmodified
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// std::string str("hello");
+    /// std::string & data = proto::_data()(i, 'a', str);
+    /// assert( &str == &data );
+    /// \endcode
     struct _data : transform<_data>
     {
         template<typename Expr, typename State, typename Data>
@@ -73,7 +100,8 @@
         {
             typedef Data result_type;
 
-            /// \param state The current data.
+            /// Returns the current data.
+            /// \param data The current data.
             /// \return \c data
             /// \throw nothrow
             typename impl::data_param operator ()(
@@ -87,35 +115,53 @@
         };
     };
 
-    /// \brief A PrimitiveTransform that returns I-th child of the current
+    /// \brief A PrimitiveTransform that returns N-th child of the current
     /// expression.
-    template<int I>
-    struct _child_c : transform<_child_c<I> >
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// proto::terminal<int>::type & j = proto::_child_c<0>()(-i);
+    /// assert( boost::addressof(i) == boost::addressof(j) );
+    /// \endcode
+    template<int N>
+    struct _child_c : transform<_child_c<N> >
     {
         template<typename Expr, typename State, typename Data>
         struct impl : transform_impl<Expr, State, Data>
         {
             typedef
-                typename result_of::child_c<Expr, I>::type
+                typename result_of::child_c<Expr, N>::type
             result_type;
 
+            /// Returns the N-th child of \c expr
+            /// \pre <tt>arity_of\<Expr\>::::value \> N</tt> 
             /// \param expr The current expression.
-            /// \return <tt>proto::child_c\<I\>(expr)</tt>
+            /// \return <tt>proto::child_c\<N\>(expr)</tt>
             /// \throw nothrow
-            typename result_of::child_c<typename impl::expr_param, I>::type
+            typename result_of::child_c<typename impl::expr_param, N>::type
             operator ()(
                 typename impl::expr_param expr
               , typename impl::state_param
               , typename impl::data_param
             ) const
             {
-                return proto::child_c<I>(expr);
+                return proto::child_c<N>(expr);
             }
         };
     };
 
     /// \brief A PrimitiveTransform that returns the value of the
     /// current terminal expression.
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// int j = proto::_value()(i);
+    /// assert( 42 == j );
+    /// \endcode
     struct _value : transform<_value>
     {
         template<typename Expr, typename State, typename Data>
@@ -125,6 +171,8 @@
                 typename result_of::value<Expr>::type
             result_type;
 
+            /// Returns the value of the specified terminal expression.
+            /// \pre <tt>arity_of\<Expr\>::::value == 0</tt>.
             /// \param expr The current expression.
             /// \return <tt>proto::value(expr)</tt>
             /// \throw nothrow
@@ -142,6 +190,15 @@
 
     /// \brief A unary CallableTransform that wraps its argument
     /// in a \c boost::reference_wrapper\<\>.
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// boost::reference_wrapper<proto::terminal<int>::type> j
+    ///     = proto::when<_, proto::_byref(_)>()(i);
+    /// assert( boost::addressof(i) == boost::addressof(j.get()) );
+    /// \endcode
     struct _byref : callable
     {
         template<typename Sig>
@@ -159,6 +216,7 @@
             typedef boost::reference_wrapper<T> const type;
         };
 
+        /// Wrap the parameter \c t in a \c boost::reference_wrapper\<\>
         /// \param t The object to wrap
         /// \return <tt>boost::ref(t)</tt>
         /// \throw nothrow
@@ -178,7 +236,16 @@
     };
 
     /// \brief A unary CallableTransform that strips references
-    /// from its argument.
+    /// and \c boost::reference_wrapper\<\> from its argument.
+    ///
+    /// Example:
+    ///
+    /// \code
+    /// proto::terminal<int>::type i = {42};
+    /// int j = 67;
+    /// int k = proto::when<_, proto::_byval(proto::_state)>()(i, boost::ref(j));
+    /// assert( 67 == k );
+    /// \endcode
     struct _byval : callable
     {
         template<typename Sig>
@@ -241,8 +308,8 @@
 
     /// INTERNAL ONLY
     ///
-    template<int I>
-    struct is_callable<_child_c<I> >
+    template<int N>
+    struct is_callable<_child_c<N> >
       : mpl::true_
     {};
 

Modified: trunk/libs/proto/doc/protodoc.xml
==============================================================================
--- trunk/libs/proto/doc/protodoc.xml	(original)
+++ trunk/libs/proto/doc/protodoc.xml	2008-08-24 02:34:00 EDT (Sun, 24 Aug 2008)
@@ -2782,44 +2782,66 @@
 
 
 
-</para></description><requires><para><computeroutput>is_expr&lt;Expr&gt;::value</computeroutput> is <computeroutput>true</computeroutput>. </para><para><computeroutput>2 == Expr::proto_arity::value</computeroutput> </para></requires><returns><para>A reference to the right child </para></returns><throws><simpara>Will not throw.</simpara></throws></overloaded-function></namespace></namespace></header><header name="boost/proto/transform.hpp"><para>Includes all the transforms in the transform/ sub-directory. </para></header><header name="boost/proto/transform/arg.hpp"><para>Contains definition of the argN transforms. </para><namespace name="boost"><namespace name="proto"><struct name="_expr"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current expression unmodified. </purpose><struct name="impl"><template>
+</para></description><requires><para><computeroutput>is_expr&lt;Expr&gt;::value</computeroutput> is <computeroutput>true</computeroutput>. </para><para><computeroutput>2 == Expr::proto_arity::value</computeroutput> </para></requires><returns><para>A reference to the right child </para></returns><throws><simpara>Will not throw.</simpara></throws></overloaded-function></namespace></namespace></header><header name="boost/proto/transform.hpp"><para>Includes all the transforms in the transform/ sub-directory. </para></header><header name="boost/proto/transform/arg.hpp"><para>Contains definition of the argN transforms. </para><namespace name="boost"><namespace name="proto"><struct name="_expr"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current expression unmodified. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ proto::terminal&lt;int&gt;::type &amp; j = proto::_expr()(i);
+ assert( boost::addressof(i) == boost::addressof(j) );
+</programlisting> </para></description><struct name="impl"><template>
       <template-type-parameter name="Expr"/>
       <template-type-parameter name="State"/>
       <template-type-parameter name="Data"/>
-    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>Expr</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::expr_param</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>An expression </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>
+    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>Expr</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::expr_param</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>The current expression. </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>Returns the current expression. 
 
 
-</para></description><returns><para><computeroutput>expr</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_state"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current state unmodified. </purpose><struct name="impl"><template>
+</para></description><returns><para><computeroutput>expr</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_state"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current state unmodified. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ char ch = proto::_state()(i, 'a');
+ assert( ch == 'a' );
+</programlisting> </para></description><struct name="impl"><template>
       <template-type-parameter name="Expr"/>
       <template-type-parameter name="State"/>
       <template-type-parameter name="Data"/>
-    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>State</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::state_param</type><parameter name=""><paramtype>typename impl::expr_param</paramtype></parameter><parameter name="state"><paramtype>typename impl::state_param</paramtype><description><para>The current state. </para></description></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>
+    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>State</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::state_param</type><parameter name=""><paramtype>typename impl::expr_param</paramtype></parameter><parameter name="state"><paramtype>typename impl::state_param</paramtype><description><para>The current state. </para></description></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>Returns the current state. 
 
 
-</para></description><returns><para><computeroutput>state</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_data"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current data unmodified. </purpose><struct name="impl"><template>
+</para></description><returns><para><computeroutput>state</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_data"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the current data unmodified. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ std::string str("hello");
+ std::string &amp; data = proto::_data()(i, 'a', str);
+ assert( &amp;str == &amp;data );
+</programlisting> </para></description><struct name="impl"><template>
       <template-type-parameter name="Expr"/>
       <template-type-parameter name="State"/>
       <template-type-parameter name="Data"/>
-    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>Data</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::data_param</type><parameter name=""><paramtype>typename impl::expr_param</paramtype></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name="data"><paramtype>typename impl::data_param</paramtype></parameter><description><para>
+    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>Data</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>impl::data_param</type><parameter name=""><paramtype>typename impl::expr_param</paramtype></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name="data"><paramtype>typename impl::data_param</paramtype><description><para>The current data. </para></description></parameter><description><para>Returns the current data. 
 
 
 </para></description><returns><para><computeroutput>data</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_child_c"><template>
-      <template-nontype-parameter name="I"><type>int</type></template-nontype-parameter>
-    </template><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns I-th child of the current expression. </purpose><struct name="impl"><template>
+      <template-nontype-parameter name="N"><type>int</type></template-nontype-parameter>
+    </template><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns N-th child of the current expression. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ proto::terminal&lt;int&gt;::type &amp; j = proto::_child_c&lt;0&gt;()(-i);
+ assert( boost::addressof(i) == boost::addressof(j) );
+</programlisting> </para></description><struct name="impl"><template>
       <template-type-parameter name="Expr"/>
       <template-type-parameter name="State"/>
       <template-type-parameter name="Data"/>
-    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>result_of::child_c&lt; Expr, I &gt;::type</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>result_of::child_c&lt; typename impl::expr_param, I &gt;::type</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>The current expression. </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>
+    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type>result_of::child_c&lt; Expr, N &gt;::type</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type>result_of::child_c&lt; typename impl::expr_param, N &gt;::type</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>The current expression. </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>Returns the N-th child of <computeroutput>expr</computeroutput> 
 
 
-</para></description><returns><para><computeroutput>proto::child_c&lt;I&gt;(expr)</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_value"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the value of the current terminal expression. </purpose><struct name="impl"><template>
+
+</para></description><requires><para><computeroutput>arity_of&lt;Expr&gt;::value &gt; N</computeroutput> </para></requires><returns><para><computeroutput>proto::child_c&lt;N&gt;(expr)</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_value"><inherit access="public">boost::proto::transform&lt; PrimitiveTransform, Base &gt;</inherit><purpose>A PrimitiveTransform that returns the value of the current terminal expression. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ int j = proto::_value()(i);
+ assert( 42 == j );
+</programlisting> </para></description><struct name="impl"><template>
       <template-type-parameter name="Expr"/>
       <template-type-parameter name="State"/>
       <template-type-parameter name="Data"/>
-    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type><classname>result_of::value</classname>&lt; Expr &gt;::type</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type><classname>result_of::value</classname>&lt; typename impl::expr_param &gt;::type</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>The current expression. </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>
+    </template><inherit access="public">boost::proto::transform_impl&lt; Expr, State, Data &gt;</inherit><typedef name="result_type"><type><classname>result_of::value</classname>&lt; Expr &gt;::type</type></typedef><method-group name="public member functions"><method name="operator()" cv="const"><type><classname>result_of::value</classname>&lt; typename impl::expr_param &gt;::type</type><parameter name="expr"><paramtype>typename impl::expr_param</paramtype><description><para>The current expression. </para></description></parameter><parameter name=""><paramtype>typename impl::state_param</paramtype></parameter><parameter name=""><paramtype>typename impl::data_param</paramtype></parameter><description><para>Returns the value of the specified terminal expression. 
+
 
 
-</para></description><returns><para><computeroutput>proto::value(expr)</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_byref"><inherit access="public">boost::proto::callable</inherit><purpose>A unary CallableTransform that wraps its argument in a <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>. </purpose><struct-specialization name="result"><template>
+</para></description><requires><para><computeroutput>arity_of&lt;Expr&gt;::value == 0</computeroutput>. </para></requires><returns><para><computeroutput>proto::value(expr)</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method></method-group></struct></struct><struct name="_byref"><inherit access="public">boost::proto::callable</inherit><purpose>A unary CallableTransform that wraps its argument in a <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ boost::reference_wrapper&lt;proto::terminal&lt;int&gt;::type&gt; j
+     = proto::when&lt;_, proto::_byref(_)&gt;()(i);
+ assert( boost::addressof(i) == boost::addressof(j.get()) );
+</programlisting> </para></description><struct-specialization name="result"><template>
       <template-type-parameter name="This"/>
       <template-type-parameter name="T"/>
     </template><specialization><template-arg>This(T &amp;)</template-arg></specialization><typedef name="type"><type>boost::reference_wrapper&lt; T &gt; const</type></typedef></struct-specialization><struct-specialization name="result"><template>
@@ -2827,12 +2849,16 @@
       <template-type-parameter name="T"/>
     </template><specialization><template-arg>This(T)</template-arg></specialization><typedef name="type"><type>boost::reference_wrapper&lt; T const  &gt; const</type></typedef></struct-specialization><method-group name="public member functions"><method name="operator()" cv="const"><type>boost::reference_wrapper&lt; T &gt; const</type><template>
           <template-type-parameter name="T"/>
-        </template><parameter name="t"><paramtype>T &amp;</paramtype><description><para>The object to wrap </para></description></parameter><description><para>
+        </template><parameter name="t"><paramtype>T &amp;</paramtype><description><para>The object to wrap </para></description></parameter><description><para>Wrap the parameter <computeroutput>t</computeroutput> in a <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput> 
 
 
 </para></description><returns><para><computeroutput>boost::ref(t)</computeroutput> </para></returns><throws><simpara>Will not throw.</simpara></throws></method><method name="operator()" cv="const"><type>boost::reference_wrapper&lt; T const  &gt; const</type><template>
           <template-type-parameter name="T"/>
-        </template><parameter name="t"><paramtype>T const &amp;</paramtype></parameter><description><para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para></description></method></method-group></struct><struct name="_byval"><inherit access="public">boost::proto::callable</inherit><purpose>A unary CallableTransform that strips references from its argument. </purpose><struct-specialization name="result"><template>
+        </template><parameter name="t"><paramtype>T const &amp;</paramtype></parameter><description><para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para></description></method></method-group></struct><struct name="_byval"><inherit access="public">boost::proto::callable</inherit><purpose>A unary CallableTransform that strips references and <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput> from its argument. </purpose><description><para>Example:</para><para><programlisting> proto::terminal&lt;int&gt;::type i = {42};
+ int j = 67;
+ int k = proto::when&lt;_, proto::_byval(proto::_state)&gt;()(i, boost::ref(j));
+ assert( 67 == k );
+</programlisting> </para></description><struct-specialization name="result"><template>
       <template-type-parameter name="This"/>
       <template-type-parameter name="T"/>
     </template><specialization><template-arg>This(boost::reference_wrapper&lt; T &gt;)</template-arg></specialization><inherit access="public">boost::proto::_byval::result&lt; This(T)&gt;</inherit></struct-specialization><struct-specialization name="result"><template>