DOC: Fix PRNG doc strings

Improve PRNG doc strings
Add Jump docstring for MT19937

Author: bashtage

randomstate/interface/dSFMT/dSFMT.pxi

@@ -155,6 +155,8 @@ hashing function is used as the initial state. Using a single 32-bit value
 for the seed can only initialize a small range of the possible initial
 state values.
 
+References
+----------
 .. [1] Mutsuo Saito and Makoto Matsumoto, "SIMD-oriented Fast Mersenne
        Twister: a 128-bit Pseudorandom Number Generator." Monte Carlo
        and Quasi-Monte Carlo Methods 2006, Springer, pp. 607 -- 622, 2008.

randomstate/interface/random-kit/random-kit.pxi

@@ -72,13 +72,6 @@ was made will be noted in the relevant docstring. Extension of existing
 parameter ranges and the addition of new parameters is allowed as long the
 previous behavior remains unchanged.
 
-``mt19937.RandomState`` can be used in parallel applications by
-calling the method ``jump`` which advances the state as-if :math:`2^{128}`
-random numbers have been generated [2]_. This allows the original sequence to
-be split so that distinct segments can be used in each worker process.  All
-generators should be initialized with the same seed to ensure that the
-segments come from the same sequence. 
-
 Parameters
 ----------
 seed : {None, int, array_like}, optional
@@ -96,4 +89,54 @@ pseudo-random number generator with a number of methods that are similar
 to the ones available in ``RandomState``. ``RandomState``, besides being
 NumPy-aware, has the advantage that it provides a much larger number
 of probability distributions to choose from.
+
+**Parallel Features**
+
+``mt19937.RandomState`` can be used in parallel applications by
+calling the method ``jump`` which advances the state as-if :math:`2^{128}`
+random numbers have been generated ([1]_, [2]_). This allows the original sequence to
+be split so that distinct segments can be used in each worker process.  All
+generators should be initialized with the same seed to ensure that the
+segments come from the same sequence.
+
+>>> from randomstate.entropy import random_entropy
+>>> import randomstate.prng.mt19937 as rnd
+>>> seed = random_entropy()
+>>> rs = [rnd.RandomState(seed) for _ in range(10)]
+# Advance rs[i] by i jumps
+>>> for i in range(10):
+        rs[i].jump(i)
+
+References
+----------
+.. [1] Hiroshi Haramoto, Makoto Matsumoto, and Pierre L\'Ecuyer, "A Fast
+       Jump Ahead Algorithm for Linear Recurrences in a Polynomial Space",
+       Sequences and Their Applications - SETA, 290--298, 2008.        
+.. [2] Hiroshi Haramoto, Makoto Matsumoto, Takuji Nishimura, François 
+       Panneton, Pierre L\'Ecuyer, "Efficient Jump Ahead for F2-Linear
+       Random Number Generators", INFORMS JOURNAL ON COMPUTING, Vol. 20, 
+       No. 3, Summer 2008, pp. 385-390.
+
+"""
+
+DEF JUMP_DOCSTRING = u"""
+jump(iter = 1)
+
+Jumps the state of the random number generator as-if 2**128 random numbers
+have been generated.
+
+Parameters
+----------
+iter : integer, positive
+    Number of times to jump the state of the prng.
+
+Returns
+-------
+out : None
+    Returns 'None' on success.
+
+Notes
+-----
+Jumping the rng state resets any pre-computed random numbers. This is required
+to ensure exact reproducibility.
 """

randomstate/interface/sfmt/sfmt.pxi

@@ -81,7 +81,7 @@ RandomState(seed=None)
 
 Container for the SIMD-based Mersenne Twister pseudo-random number generator.
 
-``dSFMT.RandomState`` exposes a number of methods for generating random
+``sfmt.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions [1]_ . In addition
 to the distribution-specific arguments, each method takes a keyword argument
 `size` that defaults to ``None``. If `size` is ``None``, then a single
@@ -91,8 +91,8 @@ then an array with that shape is filled and returned.
 
 **No Compatibility Guarantee**
 
-``dSFMT.RandomState`` does not make a guarantee that a fixed seed and a
-fixed series of calls to ``dSFMT.RandomState`` methods using the same
+``sfmt.RandomState`` does not make a guarantee that a fixed seed and a
+fixed series of calls to ``sfmt.RandomState`` methods using the same
 parameters will always produce the same results. This is different from
 ``numpy.random.RandomState`` guarantee. This is done to simplify improving
 random number generators.  To ensure identical results, you must use the
@@ -104,7 +104,7 @@ seed : {None, int, array_like}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer in [0, 2**32-1], array of integers in
     [0, 2**32-1] or ``None`` (the default). If `seed` is ``None``,
-    then ``dSFMT.RandomState`` will try to read entropy from
+    then ``sfmt.RandomState`` will try to read entropy from
     ``/dev/urandom`` (or the Windows analog) if available to
     produce a 64-bit seed. If unavailable, the a 64-bit hash of the time
     and process ID is used.
@@ -154,9 +154,14 @@ hashing function is used as the initial state. Using a single 32-bit value
 for the seed can only initialize a small range of the possible initial
 state values.
 
+References
+----------
 .. [1] Mutsuo Saito and Makoto Matsumoto, "SIMD-oriented Fast Mersenne
        Twister: a 128-bit Pseudorandom Number Generator." Monte Carlo
        and Quasi-Monte Carlo Methods 2006, Springer, pp. 607 -- 622, 2008.
+.. [2] Hiroshi Haramoto, Makoto Matsumoto, and Pierre L\'Ecuyer, "A Fast
+       Jump Ahead Algorithm for Linear Recurrences in a Polynomial Space",
+       Sequences and Their Applications - SETA, 290--298, 2008.
 """
 
 DEF JUMP_DOCSTRING = u"""

randomstate/interface/xorshift1024/xorshift1024.pxi

@@ -53,9 +53,10 @@ RandomState(seed=None)
 Container for the xorshift1024* pseudo-random number generator.
 
 xorshift1024* is a 64-bit implementation of Saito and Matsumoto's XSadd
-generator [1]_. xorshift1024* has a period of :math:`2^{1024} - 1` and
-supports jumping the sequence in increments of :math:`2^{512}`, which allows
-multiple non-overlapping sequences to be generated.
+generator [1]_ (see also [2]_, [3]_, [4]_). xorshift1024* has a period of 
+:math:`2^{1024} - 1` and supports jumping the sequence in increments of 
+:math:`2^{512}`, which allows multiple non-overlapping sequences to be 
+generated.
 
 ``xorshift1024.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. In addition to the

randomstate/interface/xorshift128/xorshift128.pxi

@@ -48,9 +48,10 @@ RandomState(seed=None)
 Container for the xorshift128+ pseudo-random number generator.
 
 xorshift128+ is a 64-bit implementation of Saito and Matsumoto's XSadd
-generator [1]_. xorshift128+ has a period of :math:`2^{128} - 1` and
-supports jumping the sequence in increments of :math:`2^{64}`, which allows
-multiple non-overlapping sequences to be generated.
+generator [1]_ (see also [2]_, [3]_, [4]_). xorshift128+ has a period of 
+:math:`2^{128} - 1` and supports jumping the sequence in increments of 
+:math:`2^{64}`, which allows multiple non-overlapping sequences to be 
+generated.
 
 ``xorshift128.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. In addition to the