Improve documentation for LTI system classes

cwrowley · cwrowley · commit 2f90b0314516 · 2015-04-20T21:56:23.000-04:00
diff --git a/control/frdata.py b/control/frdata.py
@@ -81,17 +81,14 @@
 from .lti import LTI
 
 class FRD(LTI):
-    """The FRD class represents (measured?) frequency response
-    TF instances and functions.
+    """A class for models defined by Frequency Response Data (FRD)
 
-    The FRD class is derived from the LTI parent class.  It is used
-    throughout the python-control library to represent systems in frequency
-    response data form.
+    The FRD class is used to represent systems in frequency response data form.
 
-    The main data members are 'omega' and 'fresp'. omega is a 1D
-    array with the frequency points of the response. fresp is a 3D array,
-    with the first dimension corresponding to the outputs of the FRD,
-    the second dimension corresponding to the inputs, and the 3rd dimension
+    The main data members are 'omega' and 'fresp', where `omega` is a 1D
+    array with the frequency points of the response, and `fresp` is a 3D array,
+    with the first dimension corresponding to the output index of the FRD,
+    the second dimension corresponding to the input index, and the 3rd dimension
     corresponding to the frequency points in omega.
     For example,
 
@@ -107,7 +104,7 @@ class FRD(LTI):
     epsw = 1e-8
 
     def __init__(self, *args, **kwargs):
-        """Construct a transfer function.
+        """Construct an FRD object
 
         The default constructor is FRD(d, w), where w is an iterable of
         frequency points, and d is the matching frequency data.
@@ -121,8 +118,6 @@ def __init__(self, *args, **kwargs):
         To construct frequency response data for an existing LTI
         object, other than an FRD, call FRD(sys, omega)
 
-
-
         """
         smooth = kwargs.get('smooth', False)
 
diff --git a/control/matlab.py b/control/matlab.py
@@ -522,7 +522,7 @@ def tf(*args):
 
     Returns
     -------
-    out: TransferFunction
+    out: :class:`TransferFunction`
         The new linear system
 
     Raises
@@ -541,19 +541,11 @@ def tf(*args):
     Notes
     --------
 
-    .. todo::
-
-        The next paragraph contradicts the comment in the example!
-        Also "input" should come before "output" in the sentence:
-
-        "from the (j+1)st output to the (i+1)st input"
-
     ``num[i][j]`` contains the polynomial coefficients of the numerator
-    for the transfer function from the (j+1)st output to the (i+1)st input.
+    for the transfer function from the (j+1)st input to the (i+1)st output.
     ``den[i][j]`` works the same way.
 
-    The coefficients ``[2, 3, 4]`` denote the polynomial
-    :math:`2 \cdot s^2 + 3 \cdot s + 4`.
+    The list ``[2, 3, 4]`` denotes the polynomial :math:`2s^2 + 3s + 4`.
 
     Examples
     --------
diff --git a/control/statesp.py b/control/statesp.py
@@ -90,22 +90,27 @@
 from .xferfcn import _convertToTransferFunction
 
 class StateSpace(LTI):
-    """The StateSpace class represents state space instances and functions.
+    """A class for representing state-space models
 
-    The StateSpace class is used throughout the python-control library to
-    represent systems in state space form.  This class is derived from the LTI
-    base class.
+    The StateSpace class is used to represent state-space realizations of linear
+    time-invariant (LTI) systems:
+
+        dx/dt = A x + B u
+            y = C x + D u
+
+    where u is the input, y is the output, and x is the state.
 
     The main data members are the A, B, C, and D matrices.  The class also
     keeps track of the number of states (i.e., the size of A).
 
-    Discrete time state space system are implemented by using the 'dt' class
+    Discrete-time state space system are implemented by using the 'dt' instance
     variable and setting it to the sampling period.  If 'dt' is not None,
     then it must match whenever two state space systems are combined.
     Setting dt = 0 specifies a continuous system, while leaving dt = None
     means the system timebase is not specified.  If 'dt' is set to True, the
     system will be treated as a discrete time system with unspecified
     sampling time.
+
     """
 
     def __init__(self, *args):
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -95,11 +95,10 @@
 
 class TransferFunction(LTI):
 
-    """The TransferFunction class represents TF instances and functions.
+    """A class for representing transfer functions
 
-    The TransferFunction class is derived from the LTI parent class.  It
-    is used throught the python-control library to represent systems in
-    transfer function form.
+    The TransferFunction class is used to represent systems in transfer function
+    form.
 
     The main data members are 'num' and 'den', which are 2-D lists of arrays
     containing MIMO numerator and denominator coefficients.  For example,
@@ -109,11 +108,12 @@ class TransferFunction(LTI):
     means that the numerator of the transfer function from the 6th input to the
     3rd output is set to s^2 + 4s + 8.
 
-    Discrete time transfer functions are implemented by using the 'dt' class
+    Discrete-time transfer functions are implemented by using the 'dt' instance
     variable and setting it to something other than 'None'.  If 'dt' has a
     non-zero value, then it must match whenever two transfer functions are
     combined.  If 'dt' is set to True, the system will be treated as a
     discrete time system with unspecified sampling time.
+
     """
 
     def __init__(self, *args):
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -11,8 +11,6 @@ these directly.
 .. autosummary::
    :toctree: generated/
 
-   ~lti.LTI
-   FRD
-   StateSpace
    TransferFunction
-
+   StateSpace
+   FRD
