DOC: fix some issues in signal docstrings.

- remove "default" from ricker docstring
- add plt.figure() to example
- add more math tags, elaborate on Hilbert transform

Reviewed as scipy#2455

scipy/signal/signaltools.py

@@ -773,14 +773,14 @@ def deconvolve(signal, divisor):
 
 def hilbert(x, N=None, axis=-1):
     """
-    Compute the analytic signal.
+    Compute the analytic signal, using the Hilbert transform.
 
     The transformation is done along the last axis by default.
 
     Parameters
     ----------
     x : array_like
-        Signal data
+        Signal data.  Must be real.
     N : int, optional
         Number of Fourier components.  Default: ``x.shape[axis]``
     axis : int, optional
@@ -793,14 +793,17 @@ def hilbert(x, N=None, axis=-1):
 
     Notes
     -----
-    The analytic signal `x_a(t)` of `x(t)` is::
+    The analytic signal ``x_a(t)`` of signal ``x(t)`` is:
 
-        x_a = F^{-1}(F(x) 2U) = x + i y
+    .. math:: x_a = F^{-1}(F(x) 2U) = x + i y
 
-    where ``F`` is the Fourier transform, ``U`` the unit step function,
-    and ``y`` the Hilbert transform of ``x``. [1]_
+    where `F` is the Fourier transform, `U` the unit step function,
+    and `y` the Hilbert transform of `x`. [1]_
 
-    `axis` argument is new in scipy 0.8.0.
+    In other words, the negative half of the frequency spectrum is zeroed
+    out, turning the real-valued signal into a complex signal.  The Hilbert
+    transformed signal can be obtained from ``np.imag(hilbert(x))``, and the
+    original signal from ``np.real(hilbert(x))``.
 
     References
     ----------

scipy/signal/waveforms.py

@@ -122,6 +122,7 @@ def square(t, duty=0.5):
 
     A pulse-width modulated sine wave:
 
+    >>> plt.figure()
     >>> sig = np.sin(2 * np.pi * t)
     >>> pwm = signal.square(2 * np.pi * 30 * t, duty=(sig + 1)/2)
     >>> plt.subplot(2, 1, 1)

scipy/signal/wavelets.py

@@ -277,7 +277,7 @@ def ricker(points, a):
     Parameters
     ----------
     points : int
-        Number of points in `vector`. Default is ``10 * a``.
+        Number of points in `vector`.
         Will be centered around 0.
     a : scalar
         Width parameter of the wavelet.