Fix some mistakes in documentation

cwrowley · cwrowley · commit 45e0450c0050 · 2015-04-05T11:39:59.000-04:00
Note that one cannot use arbitrary section headings in numpydoc.  For
instance, the section headings "Usage", "Keywords", and
"Return Values" are not valid section headings, and would give warnings
when building documentation.

In addition, the routine matlab.tfdata was documented incorrectly (the
documentated behavior did not match the actual behavior when keyword
arguments were used).
diff --git a/control/margins.py b/control/margins.py
@@ -86,11 +86,6 @@ def stability_margins(sysdata, deg=True, returnall=False, epsw=1e-10):
     """Calculate gain, phase and stability margins and associated
     crossover frequencies.
 
-    Usage
-    -----
-    gm, pm, sm, wg, wp, ws = stability_margins(sysdata, deg=True,
-                                               returnall=False, epsw=1e-10)
-
     Parameters
     ----------
     sysdata: linsys or (mag, phase, omega) sequence
diff --git a/control/matlab.py b/control/matlab.py
@@ -1509,7 +1509,7 @@ def ssdata(sys):
     return (ss.A, ss.B, ss.C, ss.D)
 
 # Return transfer function data as a tuple
-def tfdata(sys, **kw):
+def tfdata(sys):
     '''
     Return transfer function data objects for a system
 
@@ -1518,17 +1518,12 @@ def tfdata(sys, **kw):
     sys: Lti (StateSpace, or TransferFunction)
         LTI system whose data will be returned
 
-    Keywords
-    --------
-    inputs = int; outputs = int
-        For MIMO transfer function, return num, den for given inputs, outputs
-
     Returns
     -------
     (num, den): numerator and denominator arrays
         Transfer function coefficients (SISO only)
     '''
-    tf = _convertToTransferFunction(sys, **kw)
+    tf = _convertToTransferFunction(sys)
 
     return (tf.num, tf.den)
 
diff --git a/control/nichols.py b/control/nichols.py
@@ -103,10 +103,6 @@ def nichols_plot(syslist, omega=None, grid=True):
 def nichols_grid(cl_mags=None, cl_phases=None):
     """Nichols chart grid
 
-    Usage
-    =====
-    nichols_grid()
-
     Plots a Nichols chart grid on the current axis, or creates a new chart
     if no plot already exists.
 
@@ -119,8 +115,8 @@ def nichols_grid(cl_mags=None, cl_phases=None):
         Array of closed-loop phases defining the iso-phase lines on a custom
         Nichols chart. Must be in the range -360 < cl_phases < 0
 
-    Return values
-    -------------
+    Returns
+    -------
     None
     """
     # Default chart size
@@ -211,19 +207,15 @@ def closed_loop_contours(Gcl_mags, Gcl_phases):
     Gol is an open-loop transfer function, and Gcl is a corresponding
     closed-loop transfer function.
 
-    Usage
-    =====
-    contours = closed_loop_contours(Gcl_mags, Gcl_phases)
-
     Parameters
     ----------
     Gcl_mags : array-like
         Array of magnitudes of the contours
     Gcl_phases : array-like
         Array of phases in radians of the contours
 
-    Return values
-    -------------
+    Returns
+    -------
     contours : complex array
         Array of complex numbers corresponding to the contours.
     """
@@ -241,10 +233,6 @@ def m_circles(mags, phase_min=-359.75, phase_max=-0.25):
     Gol is an open-loop transfer function, and Gcl is a corresponding
     closed-loop transfer function.
 
-    Usage
-    =====
-    contours = m_circles(mags, phase_min, phase_max)
-
     Parameters
     ----------
     mags : array-like
@@ -254,8 +242,8 @@ def m_circles(mags, phase_min=-359.75, phase_max=-0.25):
     phase_max : degrees
         Maximum phase in degrees of the N-circles
 
-    Return values
-    -------------
+    Returns
+    -------
     contours : complex array
         Array of complex numbers corresponding to the contours.
     """
@@ -271,10 +259,6 @@ def n_circles(phases, mag_min=-40.0, mag_max=12.0):
     Gol is an open-loop transfer function, and Gcl is a corresponding
     closed-loop transfer function.
 
-    Usage
-    =====
-    contours = n_circles(phases, mag_min, mag_max)
-
     Parameters
     ----------
     phases : array-like
@@ -284,8 +268,8 @@ def n_circles(phases, mag_min=-40.0, mag_max=12.0):
     mag_max : dB
         Maximum magnitude in dB of the N-circles
 
-    Return values
-    -------------
+    Returns
+    -------
     contours : complex array
         Array of complex numbers corresponding to the contours.
     """
