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

Subject: [Boost-commit] svn:boost r49014 - in sandbox/thread_safe_signals/trunk: boost/signals2 libs/signals2/doc/reference
From: fmhess_at_[hidden]
Date: 2008-09-29 13:10:42

Author: fmhess
Date: 2008-09-29 13:10:41 EDT (Mon, 29 Sep 2008)
New Revision: 49014
URL: http://svn.boost.org/trac/boost/changeset/49014

Log:
Added scoped_connection::released() query, mostly because it makes it
easier to document the class' behavior.  Updated scoped_connection
documentation to make it more complete and up to date.

Text files modified: 
   sandbox/thread_safe_signals/trunk/boost/signals2/connection.hpp              |     1                                         
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/connection.xml |   137 +++++++++++++++++++++++++++++++++------ 
   2 files changed, 117 insertions(+), 21 deletions(-)

Modified: sandbox/thread_safe_signals/trunk/boost/signals2/connection.hpp
==============================================================================
--- sandbox/thread_safe_signals/trunk/boost/signals2/connection.hpp	(original)
+++ sandbox/thread_safe_signals/trunk/boost/signals2/connection.hpp	2008-09-29 13:10:41 EDT (Mon, 29 Sep 2008)
@@ -221,6 +221,7 @@
         _released = true;
         return conn;
       }
+      bool released() const {return _released;}
       void swap(scoped_connection &other)
       {
         connection::swap(other);

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/connection.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/connection.xml	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/connection.xml	2008-09-29 13:10:41 EDT (Mon, 29 Sep 2008)
@@ -153,31 +153,126 @@
         <inherit access="public">
           <type><classname>connection</classname></type>
         </inherit>
-        <inherit access="private">
-          <type><classname>noncopyable</classname></type>
-          <purpose>Exposition only</purpose>
-        </inherit>
         <purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose>
 
-        <constructor>
-          <parameter name="other">
-            <paramtype>const <classname>connection</classname>&amp;</paramtype>
-          </parameter>
-
-          <effects><para><computeroutput>this</computeroutput> references
-          the connection referenced by
-          <computeroutput>other</computeroutput>.</para></effects>
-
-          <throws><para>Will not throw.</para></throws>
-        </constructor>
-
-        <destructor>
-          <effects><para>If
-          <computeroutput>this-&gt;<methodname alt="connection::connected">connected</methodname>()</computeroutput>,
-          disconnects the signal-slot connection.</para></effects>
-        </destructor>
+        <access name="public">
+          <constructor>
+            <postconditions>
+              <para><code><methodname>released</methodname>() == false &amp;&amp; <methodname alt="connection::connected">connected</methodname>() == false </code></para>
+            </postconditions>
+            <description>
+              <para>Default constructs an empty scoped_connection.</para>
+            </description>
+
+            <throws><para>Will not throw.</para></throws>
+          </constructor>
+          <constructor>
+            <parameter name="other">
+              <paramtype>const <classname>connection</classname>&amp;</paramtype>
+            </parameter>
+
+            <effects><para><computeroutput>this</computeroutput> references
+              the connection referenced by
+              <computeroutput>other</computeroutput>.</para></effects>
+
+            <postconditions>
+              <para><code><methodname>released</methodname>() == false &amp;&amp; <methodname alt="connection::connected">connected</methodname>() == other.connected()</code></para>
+            </postconditions>
 
+            <throws><para>Will not throw.</para></throws>
+          </constructor>
+
+          <destructor>
+            <effects><para>If
+            <computeroutput>this-&gt;<methodname alt="connection::connected">connected</methodname>()</computeroutput>
+            and this-><methodname>released</methodname>() == false,
+            disconnects the signal-slot connection.</para></effects>
+          </destructor>
+          <method-group name="public methods">
+            <method name="operator=">
+              <type>scoped_connection &amp;</type>
+              <parameter name="rhs">
+                <paramtype>const connection &amp;</paramtype>
+              </parameter>
+              <effects>
+                <para><computeroutput>this</computeroutput> references
+                  the connection referenced by
+                  <computeroutput>rhs</computeroutput>.  If <code>this</code> already references another
+                  connection which has not been released, the old connection will be disconnected first.
+                </para>
+              </effects>
+              <postconditions>
+               <para><code><methodname>released</methodname>() == false &amp;&amp; <methodname alt="connection::connected">connected</methodname>() == rhs.connected()</code></para>
+              </postconditions>
+            </method>
+            <method name="release">
+              <type><classname>connection</classname></type>
+              <postconditions>
+                <para><code>released() == true</code></para>
+              </postconditions>
+              <effects>
+                <para>
+                  Prevents the <code>scoped_connection</code> from disconnecting when the
+                  it is destroyed or reassigned.
+                </para>
+              </effects>
+            </method>
+            <method name="released" cv="const">
+              <type>bool</type>
+              <returns>
+                <para>
+                  Returns <code>false</code> if the scoped_connection will disconnect the connection when the
+                  <code>scoped_connection</code> is destroyed or reassigned.  Otherwise, returns <code>true</code>.
+                </para>
+              </returns>
+            </method>
+            <method name="swap">
+              <type>void</type>
+              <parameter name="other">
+                <paramtype>const <classname>scoped_connection</classname>&amp;</paramtype>
+              </parameter>
+              <effects><para>Swaps the connections referenced in
+              <computeroutput>this</computeroutput> and
+              <computeroutput>other</computeroutput>, as well as their "released" state
+              (see the <methodname>released</methodname> method).</para></effects>
+
+              <throws><para>Will not throw.</para></throws>
+            </method>
+          </method-group>
+        </access>
+        <access name="private">
+          <constructor>
+            <parameter name="other">
+              <paramtype>const <classname>scoped_connection</classname>&amp;</paramtype>
+            </parameter>
+            <description>
+              <para>The scoped_connection class is not copyable.  It may only be constructed from a <classname>connection</classname> object.</para>
+            </description>
+          </constructor>
+          <copy-assignment>
+            <parameter name="rhs">
+              <paramtype>const <classname>scoped_connection</classname>&amp;</paramtype>
+            </parameter>
+            <description>
+              <para>The scoped_connection class is not copyable.  It may only be assigned from a <classname>connection</classname> object.</para>
+            </description>
+          </copy-assignment>
+        </access>
         <description><para>A connection which automatically disconnects on destruction.</para></description>
+        <free-function-group name="specialized algorithms">
+          <function name="swap">
+            <type>void</type>
+            <parameter name="x">
+              <paramtype><classname>scoped_connection</classname>&amp;</paramtype>
+            </parameter>
+            <parameter name="y">
+              <paramtype><classname>scoped_connection</classname>&amp;</paramtype>
+            </parameter>
+
+            <effects><para><computeroutput>x.swap(y)</computeroutput></para></effects>
+            <throws><para>Will not throw.</para></throws>
+          </function>
+        </free-function-group>
       </class>
     </namespace>
   </namespace>