[Boost-commit] svn:boost r50789 - in sandbox/thread_safe_signals/trunk/libs/signals2/doc: . reference

Subject: [Boost-commit] svn:boost r50789 - in sandbox/thread_safe_signals/trunk/libs/signals2/doc: . reference
From: fmhess_at_[hidden]
Date: 2009-01-26 13:58:01

Author: fmhess
Date: 2009-01-26 13:58:00 EST (Mon, 26 Jan 2009)
New Revision: 50789
URL: http://svn.boost.org/trac/boost/changeset/50789

Log:
Added reference documentation for signal_type.

Added:
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_type.xml   (contents, props changed)
Text files modified: 
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile                    |     1 +                                       
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml     |     1 +                                       
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_header.xml |    14 +++++++++++---                          
   3 files changed, 13 insertions(+), 3 deletions(-)

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile	2009-01-26 13:58:00 EST (Mon, 26 Jan 2009)
@@ -25,6 +25,7 @@
         reference/shared_connection_block.xml \
         reference/signal_base.xml \
         reference/signal_header.xml \
+	reference/signal_type.xml \
         reference/slot_base.xml \
         reference/slot.xml \
         reference/trackable.xml \

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml	2009-01-26 13:58:00 EST (Mon, 26 Jan 2009)
@@ -22,6 +22,7 @@
   <xi:include href="shared_connection_block.xml"/>
   <xi:include href="signal_header.xml"/>
   <xi:include href="signal_base.xml"/>
+  <xi:include href="signal_type.xml"/>
   <xi:include href="slot.xml"/>
   <xi:include href="slot_base.xml"/>
   <xi:include href="trackable.xml"/>

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_header.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_header.xml	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_header.xml	2009-01-26 13:58:00 EST (Mon, 26 Jan 2009)
@@ -60,11 +60,11 @@
         <typedef name="group_compare_type"><type>GroupCompare</type></typedef>
         <typedef name="slot_function_type"><type>SlotFunction</type></typedef>
         <typedef name="slot_type">
-          <type><classname>slotN</classname>&lt;R, T1, T2, ..., TN, SlotFunction&gt;</type>
+          <type>typename <classname>slotN</classname>&lt;R, T1, T2, ..., TN, SlotFunction&gt;</type>
         </typedef>
         <typedef name="extended_slot_function_type"><type>ExtendedSlotFunction</type></typedef>
         <typedef name="extended_slot_type">
-          <type><classname>slotN</classname>&lt;R, const <classname>connection</classname> &amp;, T1, T2, ..., TN, ExtendedSlotFunction&gt;</type>
+          <type>typename <classname>slotN</classname>&lt;R, const <classname>connection</classname> &amp;, T1, ..., TN, ExtendedSlotFunction&gt;</type>
           <description>
             <para>Slots of the <code>extended_slot_type</code> may be connected to the signal using the
               <methodname>connect_extended</methodname> methods.  The <code>extended_slot_type</code>
@@ -75,7 +75,7 @@
           </description>
         </typedef>
         <typedef name="slot_result_type">
-          <type><emphasis>unspecified</emphasis></type>
+          <type><emphasis>implementation-detail</emphasis></type>
           <description>
             <para>
               This is the type returned when dereferencing the input iterators passed to the signal's
@@ -425,6 +425,14 @@
 
           <para>All functionality of this class template is in its base
           class <classname>signalN</classname>.</para>
+          <para>
+            The large number of template parameters for the <code>signal</code> class
+            can be an inconvenience.  The
+            the <classname>signal_type</classname> metafunction is provided to
+            overcome this problem.  It uses the Boost.Parameter library
+            to permit specification of the <code>signal</code> class' template type parameters
+            as named parameters.
+          </para>
         </description>
 
         <constructor>

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_type.xml
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/signal_type.xml	2009-01-26 13:58:00 EST (Mon, 26 Jan 2009)
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<header name="boost/signals2/signal_type.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
+  <namespace name="boost">
+    <namespace name="signals2">
+      <namespace name="keywords">
+        <class name="signature_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="Signature"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>Signature</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(signature_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="combiner_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="Combiner"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>Combiner</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(combiner_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="group_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="Group"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>Group</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(group_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="group_compare_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="GroupCompare"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>GroupCompare</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(group_compare_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="slot_function_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="SlotFunction"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>SlotFunction</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(slot_function_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="extended_slot_function_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="ExtendedSlotFunction"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>ExtendedSlotFunction</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(extended_slot_function_type)</code>
+            </para>
+          </description>
+        </class>
+        <class name="mutex_type">
+          <inherit access="public"><emphasis>unspecified-type</emphasis></inherit>
+          <template>
+            <template-type-parameter name="Mutex"/>
+          </template>
+          <purpose>A template keyword for <classname>signal_type</classname>.</purpose>
+          <description>
+            <para>
+              This class is a template keyword which may be used to pass the wrapped <code>Mutex</code>
+              template type to the <classname>signal_type</classname> metafunction as a named parameter.
+            </para>
+            <para>
+              The code for this class is generated by a calling a macro from the Boost.Parameter library:
+              <code>BOOST_PARAMETER_TEMPLATE_KEYWORD(mutex_type)</code>
+            </para>
+          </description>
+        </class>
+      </namespace>
+      <class name="signal_type">
+        <template>
+          <template-type-parameter name="A0"/>
+          <template-type-parameter name="A1">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+          <template-type-parameter name="A2">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+          <template-type-parameter name="A3">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+          <template-type-parameter name="A4">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+          <template-type-parameter name="A5">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+          <template-type-parameter name="A6">
+            <default>boost::parameter::void_</default>
+          </template-type-parameter>
+        </template>
+        <purpose>Specify a the template type parameters of a boost::signals2::signal using named parameters.</purpose>
+        <description>
+          <para>The <code>signal_type</code> metafunction employs the Boost.Parameter library to
+            allow users to specify the template type parameters of a <classname>signal</classname>
+            using named parameters.  The resulting signal type is provided through the
+            <classname>signal_type::type</classname> typedef.  Named template type parameters
+            can enhance readability of code, and provide convenience for specifying classes
+            which have a large number of template parameters.
+          </para>
+          <para>The template type parameters may be passed positionally, similarly to passing them
+            to the <classname>signal</classname> class directly.  Or, they may be passed as named template parameters
+            by wrapping them in one of the template keyword classes provided in the
+            <code>boost::signals2::keywords</code> namespace.  The supported template keywords are:
+            <classname>keywords::signature_type</classname>, <classname>keywords::combiner_type</classname>,
+            <classname>keywords::group_type</classname>, <classname>keywords::group_compare_type</classname>,
+            <classname>keywords::slot_function_type</classname>, <classname>keywords::extended_slot_function_type</classname>,
+            and <classname>keywords::mutex_type</classname>.
+          </para>
+          <para>The default types for unspecified template type parameters are the same as those for the
+            <classname>signal</classname> class.
+          </para>
+          <para>
+            Named template type parameters enhance are especially convenient when you only wish to change a
+            few of a signal's template type parameters from their defaults, and the parameters
+            you wish to change are near the end of the signal's template parameter list.
+            For example, if you only wish to change the <code>Mutex</code> template type
+            parameter of a signal, you might write:
+          </para>
+<programlisting>namespace bs2 = boost::signals2;
+using bs2::keywords;
+bs2::signal_type&lt;void (), mutex_type&lt;bs2::dummy_mutex&gt; &gt;::type sig;
+</programlisting>
+          <para>For comparison, to specify the same type using the signal class directly looks like:</para>
+<programlisting>namespace bs2 = boost::signals2;
+bs2::signal
+  &lt;
+    void (),
+    bs2::optional_last_value&lt;void&gt;,
+    int,
+    std::less&lt;int&gt;,
+    boost::function&lt;void ()&gt;,
+    boost::function&lt;void (const connection &amp;)&gt;,
+    bs2::dummy_mutex
+  &gt; sig;
+</programlisting>
+        </description>
+        <typedef name="signature_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="combiner_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="group_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="group_compare_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="slot_function_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="extended_slot_function_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="mutex_type">
+          <type><emphasis>implementation-detail</emphasis></type>
+        </typedef>
+        <typedef name="type">
+          <type>typename signal&lt;signature_type, combiner_type, ..., mutex_type&gt;</type>
+        </typedef>
+      </class>
+    </namespace>
+  </namespace>
+</header>