address remaining @sawyerbfuller review comments

Author: murrayrm

control/lti.py

@@ -44,7 +44,43 @@ def __init__(self, inputs=1, outputs=1, states=None, name=None, **kwargs):
     def __call__(self, x, squeeze=None, warn_infinite=True):
         """Evaluate system transfer function at point in complex plane.
 
-        See `StateSpace.__call__` and `TransferFunction.__call__` for details.
+        Returns the value of the system's transfer function at a point `x`
+        in the complex plane, where `x` is `s` for continuous-time systems
+        and `z` for discrete-time systems.
+
+        By default, a (complex) scalar will be returned for SISO systems
+        and a p x m array will be return for MIMO systems with m inputs and
+        p outputs.  This can be changed using the `squeeze` keyword.
+
+        To evaluate at a frequency `omega` in radians per second,
+        enter ``x = omega * 1j`` for continuous-time systems,
+        ``x = exp(1j * omega * dt)`` for discrete-time systems, or
+        use the `~LTI.frequency_response` method.
+
+        Parameters
+        ----------
+        x : complex or complex 1D array_like
+            Complex value(s) at which transfer function will be evaluated.
+        squeeze : bool, optional
+            Squeeze output, as described below.  Default value can be set
+            using `config.defaults['control.squeeze_frequency_response']`.
+        warn_infinite : bool, optional
+            If set to False, turn off divide by zero warning.
+
+        Returns
+        -------
+        fresp : complex ndarray
+            The value of the system transfer function at `x`.  If the system
+            is SISO and `squeeze` is not True, the shape of the array matches
+            the shape of `x`.  If the system is not SISO or `squeeze` is
+            False, the first two dimensions of the array are indices for the
+            output and input and the remaining dimensions match `x`.  If
+            `squeeze` is True then single-dimensional axes are removed.
+
+        Notes
+        -----
+        See `FrequencyResponseData`.__call__`, `StateSpace.__call__`,
+        `TransferFunction.__call__` for class-specific details.
 
         """
         raise NotImplementedError("not implemented in subclass")
@@ -117,7 +153,7 @@ def frequency_response(self, omega=None, squeeze=None):
 
     def dcgain(self):
         """Return the zero-frequency (DC) gain."""
-        return NotImplemented
+        raise NotImplementedError("dcgain not defined for subclass")
 
     def _dcgain(self, warn_infinite):
         zeroresp = self(0 if self.isctime() else 1,
@@ -443,8 +479,7 @@ def evalfr(sys, x, squeeze=None):
 
     See Also
     --------
-    StateSpace.__call__, TransferFunction.__call__, frequency_response, \
-    bode_plot
+    LTI.__call__, frequency_response, bode_plot
 
     Notes
     -----

control/statesp.py

@@ -1746,7 +1746,7 @@ def ss(*args, **kwargs):
 
     See Also
     --------
-    tf, ss2tf, tf2ss, zpk
+    StateSpace, nlsys, tf, ss2tf, tf2ss, zpk
 
     Notes
     -----

doc/xferfcn.rst

@@ -38,6 +38,7 @@ domain properties of a linear systems:
    frequency_response
    phase_crossover_frequencies
    singular_values_response
+   stability_margins
    tfdata
 
 These functions work on both state space and transfer function models.