Updated documentation

base_tensor.py

-"""A simple class to store L{numpy.ndarray} data """
+"""
+A simple class to store L{numpy.ndarray} data
+"""
 
 from gof import Result, Op, utils, AbstractFunctionError
 import numpy
@@ -12,6 +14,12 @@ from copy import copy
 class BaseTensor(Result):
     """
     L{Result} to store L{numpy.ndarray} or equivalent via .data
+
+    This class does not implement python operators and has no dependencies
+    on the L{Op}s that use it.
+
+    @todo: At some point we should document a glossary, such as terms like
+    broadcasting and shape.
     
     @type _dtype: numpy dtype string such as 'int64' or 'float64' (among others)
     @type _broadcastable: tuple or list or array of boolean values, whose length
@@ -21,16 +29,6 @@ class BaseTensor(Result):
         - False means the dimension can be anything.
         - True means  the dimension must be 1. Also, this dimension will be considered
           for L{broadcasting}, as described and implemented in Numpy.
-
-    Properties:
-    dtype - read-only access to _dtype, which should not be changed
-    broadcastable - read-only access to _broadcastable, which should not be changed
-
-    This class does not implement python operators and has no dependencies
-    on the L{Op}s that use it.
-
-    @todo At some point we should document a glossary, such as terms like
-    broadcasting and shape.
     """
 
     def __init__(self, dtype, broadcastable, name=None):
@@ -225,8 +223,8 @@ class BaseTensor(Result):
     # Tensor specific attributes
     ############################
 
-    dtype = property(lambda self: self._dtype)
-    broadcastable = property(lambda self: self._broadcastable)
+    dtype = property(lambda self: self._dtype, doc = "read-only access to _dtype, which should not be changed")
+    broadcastable = property(lambda self: self._broadcastable, doc = "read-only access to _broadcastable, which should not be changed")
 
     ############################
     # Cloning facilities

gof/cc.py

@@ -84,19 +84,19 @@ def failure_code(sub):
 def code_gen(blocks):
     """
     From a list of L{CodeBlock} instances, returns a string that executes them
-    all in sequence. eg for (decl1, task1, cleanup1) and (decl2, task2, cleanup2)
-    the returned string will be of the form:
-
-    decl1
-    decl2
-    {
-     task1
-     {
-      task2
-      cleanup2
-     }
-     cleanup1
-    }
+    all in sequence. eg for C{(decl1, task1, cleanup1)} and C{(decl2, task2, cleanup2)}
+    the returned string will be of the form::
+
+        decl1
+        decl2
+        {
+         task1
+         {
+          task2
+          cleanup2
+         }
+         cleanup1
+        }
     """
 
     decl = ""
@@ -278,10 +278,9 @@ def get_c_sync(r, name, sub):
 
 def apply_policy(policy, r, name, sub):
     """
-    policy -> list of functions that map a Result to a string,
-              or a single such function
-    r -> a Result
-    returns policy[0](r) + policy[1](r) + ...
+    @param policy: list of functions that map a L{Result} to a string, or a single such function
+    @type r: L{Result}
+    @return: C{policy[0](r) + policy[1](r) + ...}
     """
     if isinstance(r, (list, tuple)):
         ret = ""

gof/opt.py

-
 from op import Op
 from result import Result
 from env import InconsistencyError

gof/result.py

@@ -43,15 +43,6 @@ class Result(object):
      - _data - anything
      - state - one of (Empty, Allocated, Computed)
      - name - string
-
-    Properties:
-     - role - (rw)
-     - owner - (ro)
-     - index - (ro)
-     - data - (rw) : calls data_filter when setting
-
-    Abstract Methods:
-     - data_filter
     """
 
     __slots__ = ['_role', '_data', 'state', '_name', '_hash_id']
@@ -106,7 +97,7 @@ class Result(object):
         #assert owner.outputs[index] is self
         self._role = role
 
-    role = property(__get_role, __set_role)
+    role = property(__get_role, __set_role, doc="(writeable)")
 
     #
     # owner
@@ -117,7 +108,7 @@ class Result(object):
         return self._role[0]
 
     owner = property(__get_owner, 
-                     doc = "Op of which this Result is an output, or None if role is None")
+                     doc = "Op of which this Result is an output, or None if role is None (read-only)")
 
     #
     # index
@@ -128,7 +119,7 @@ class Result(object):
         return self._role[1]
 
     index = property(__get_index,
-                     doc = "position of self in owner's outputs, or None if role is None")
+                     doc = "position of self in owner's outputs, or None if role is None (read-only)")
 
 
     # 
@@ -156,7 +147,7 @@ class Result(object):
         self.state = Computed
         
     data = property(__get_data, __set_data,
-                    doc = "The storage associated with this result")
+                    doc = "The storage associated with this result (writeable)")
 
     def filter(self, data):
         """

sparse.py

@@ -76,13 +76,9 @@ def assparse(sp, **kwargs):
 
 class SparseResult(gof.result.Result):
     """
-    Attribute:
-     - format - a string identifying the type of sparsity
-
-    Properties:
-    - T - read-only: return a transpose of self
-
-    Methods:
+    @type _dtype: numpy dtype string such as 'int64' or 'float64' (among others)
+    @type _format: string
+    @ivar _format: The sparse storage strategy.
 
     @note As far as I can tell, L{scipy.sparse} objects must be matrices, i.e. have dimension 2.
     """
@@ -94,7 +90,7 @@ class SparseResult(gof.result.Result):
 
     def __init__(self, dtype, format, **kwargs):
         """
-        Fundamental way to do create a sparse node.
+        Fundamental way to create a sparse node.
         @param dtype:   Type of numbers in the matrix.
         @param format:  The sparse storage strategy.
         @return         An empty SparseResult instance.
@@ -134,7 +130,7 @@ class SparseResult(gof.result.Result):
 
     dtype = property(lambda self: self._dtype)
     format = property(lambda self: self._format)
-    T = property(lambda self: transpose(self), doc = "Return aliased transpose")
+    T = property(lambda self: transpose(self), doc = "Return aliased transpose of self (read-only)")
 
 
     def __add__(left, right): return add(left, right)