[Commit-gnuradio] r7718 - in gnuradio/trunk/gnuradio-core/src: lib/runtime python/gnuradio/gr

[jcorgan]

Author: jcorgan
Date: 2008-02-16 11:10:29 -0700 (Sat, 16 Feb 2008)
New Revision: 7718

Modified:
   gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_hier_block2.h
   gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_top_block.h
   gnuradio/trunk/gnuradio-core/src/python/gnuradio/gr/hier_block2.py
Log:
Improve hierarchical block documentation.

Modified: gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_hier_block2.h
===================================================================
--- gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_hier_block2.h       
2008-02-16 16:55:59 UTC (rev 7717)
+++ gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_hier_block2.h       
2008-02-16 18:10:29 UTC (rev 7718)
@@ -60,20 +60,75 @@
 public:
   virtual ~gr_hier_block2();
   
+  /*!
+   * \brief Add a stand-alone (possibly hierarchical) block to internal graph
+   *
+   * This adds a gr-block or hierarchical block to the internal graph
+   * without wiring it to anything else.
+   */
   void connect(gr_basic_block_sptr block);
 
+  /*!
+   * \brief Add gr-blocks or hierarchical blocks to internal graph and wire 
together
+   *
+   * This adds (if not done earlier by another connect) a pair of gr-blocks or 
+   * hierarchical blocks to the internal flowgraph, and wires the specified 
output 
+   * port to the specified input port.
+   */
   void connect(gr_basic_block_sptr src, int src_port, 
               gr_basic_block_sptr dst, int dst_port);
 
+  /*!
+   * \brief Remove a gr-block or hierarchical block from the internal 
flowgraph.
+   *
+   * This removes a gr-block or hierarchical block from the internal flowgraph,
+   * disconnecting it from other blocks as needed.
+   *
+   */
   void disconnect(gr_basic_block_sptr block);
 
+  /*!
+   * \brief Disconnect a pair of gr-blocks or hierarchical blocks in internal
+   *        flowgraph.
+   *
+   * This disconnects the specified input port from the specified output port
+   * of a pair of gr-blocks or hierarchical blocks.
+   */
   void disconnect(gr_basic_block_sptr src, int src_port,
                  gr_basic_block_sptr dst, int dst_port);
 
+  /*!
+   * \brief Disconnect all connections in the internal flowgraph.
+   *
+   * This call removes all output port to input port connections in the 
internal
+   * flowgraph.
+   */
   void disconnect_all();
+
+  /*!
+   * Lock a flowgraph in preparation for reconfiguration.  When an equal
+   * number of calls to lock() and unlock() have occurred, the flowgraph
+   * will be restarted automatically.
+   *
+   * N.B. lock() and unlock() cannot be called from a flowgraph thread
+   * (E.g., gr_block::work method) or deadlock will occur when
+   * reconfiguration happens.
+   */
   virtual void lock();
+
+  /*!
+   * Unlock a flowgraph in preparation for reconfiguration.  When an equal
+   * number of calls to lock() and unlock() have occurred, the flowgraph
+   * will be restarted automatically.
+   *
+   * N.B. lock() and unlock() cannot be called from a flowgraph thread
+   * (E.g., gr_block::work method) or deadlock will occur when
+   * reconfiguration happens.
+   */
   virtual void unlock();
 
+  // This is a public method for ease of code organization, but should be
+  // ignored by the user.
   gr_flat_flowgraph_sptr flatten() const;
 };
 

Modified: gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_top_block.h
===================================================================
--- gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_top_block.h 2008-02-16 
16:55:59 UTC (rev 7717)
+++ gnuradio/trunk/gnuradio-core/src/lib/runtime/gr_top_block.h 2008-02-16 
18:10:29 UTC (rev 7718)
@@ -89,7 +89,7 @@
   virtual void lock();
 
   /*!
-   * Lock a flowgraph in preparation for reconfiguration.  When an equal
+   * Unlock a flowgraph in preparation for reconfiguration.  When an equal
    * number of calls to lock() and unlock() have occurred, the flowgraph
    * will be restarted automatically.
    *

Modified: gnuradio/trunk/gnuradio-core/src/python/gnuradio/gr/hier_block2.py
===================================================================
--- gnuradio/trunk/gnuradio-core/src/python/gnuradio/gr/hier_block2.py  
2008-02-16 16:55:59 UTC (rev 7717)
+++ gnuradio/trunk/gnuradio-core/src/python/gnuradio/gr/hier_block2.py  
2008-02-16 18:10:29 UTC (rev 7718)
@@ -30,16 +30,36 @@
 # It also allows us to intercept method calls if needed
 #
 class hier_block2(object):
+    """
+    Python wrapper around the C++ hierarchical block implementation.
+    Provides convenience functions and allows proper Python subclassing.
+    """
+
     def __init__(self, name, input_signature, output_signature):
+        """
+        Create a hierarchical block with a given name and I/O signatures.
+        """
        self._hb = hier_block2_swig(name, input_signature, output_signature)
 
     def __getattr__(self, name):
+        """
+        Pass-through member requests to the C++ object.
+        """
        return getattr(self._hb, name)
 
     def connect(self, *points):
-        '''connect requires one or more arguments that can be coerced to 
endpoints.
-        If more than two arguments are provided, they are connected together 
successively.
-        '''
+        """
+        Connect two or more block endpoints.  An endpoint is either a (block, 
port)
+        tuple, or just a block type.  In the latter case, the port number is 
assumed
+        to be zero.
+
+        To connect the hierarchical block external inputs or outputs to 
internal block
+        inputs or outputs, use 'self' in the connect call.
+
+        If multiple arguments are provided, connect will attempt to wire them 
in series,
+        interpreting the endpoints as inputs or outputs as appropriate.
+        """
+
         if len (points) < 1:
             raise ValueError, ("connect requires at least one endpoint; %d 
provided." % (len (points),))
        else:
@@ -65,9 +85,15 @@
                 raise ValueError("unable to coerce endpoint")
 
     def disconnect(self, *points):
-        '''connect requires one or more arguments that can be coerced to 
endpoints.
+        """
+        Disconnect two endpoints in the flowgraph.
+
+        To disconnect the hierarchical block external inputs or outputs to 
internal block
+        inputs or outputs, use 'self' in the connect call.
+
         If more than two arguments are provided, they are disconnected 
successively.
-        '''
+        """
+        
         if len (points) < 1:
             raise ValueError, ("disconnect requires at least two endpoints; %d 
provided." % (len (points),))
         else: