Enable docs for the new test modules and clean them up.

diff --git a/doc/source/developer-api.rst b/doc/source/developer-api.rst
index aa7898fe1ede7e747395fec4fc5d2a44850e753a..39d2611bd7fa9e9129170d375c5660db4e9b4fa2 100644 (file)
--- a/doc/source/developer-api.rst
+++ b/doc/source/developer-api.rst
@@ -52,6 +52,22 @@ test module
   :undoc-members:
   :show-inheritance:
 
+test.matrices_test
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: test.matrices_test
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+test.randomgen
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: test.randomgen
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
 test.symmetric_linear_game_test module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/test/randomgen.py b/test/randomgen.py
index afe0dae25304b33e2f01e3fd2cb46ca824cc8771..395408c6626ec4ee48dcb95e3b2e684daea88f4a 100644 (file)
--- a/test/randomgen.py
+++ b/test/randomgen.py
@@ -23,12 +23,14 @@ properties within reason.
 
 def random_scalar():
     """
-    Generate a random scalar in ``[-RANDOM_MAX, RANDOM_MAX]``.
+    Generate a random scalar.
 
     Returns
     -------
 
     float
+        A random real number between ``-RANDOM_MAX`` and ``RANDOM_MAX``,
+        inclusive.
 
     Examples
     --------
@@ -42,12 +44,14 @@ def random_scalar():
 
 def random_nn_scalar():
     """
-    Generate a random nonnegative scalar in ``[0, RANDOM_MAX]``.
+    Generate a random nonnegative scalar.
 
     Returns
     -------
 
     float
+        A random nonnegative real number between zero and ``RANDOM_MAX``,
+        inclusive.
 
     Examples
     --------
@@ -61,13 +65,13 @@ def random_nn_scalar():
 
 def random_natural():
     """
-    Generate a random natural number between ``1 and RANDOM_MAX``
-    inclusive.
+    Generate a random natural number.
 
     Returns
     -------
 
     int
+        A random natural number between ``1`` and ``RANDOM_MAX`` inclusive.
 
     Examples
     --------
@@ -98,7 +102,7 @@ def random_matrix(row_count, column_count=None):
 
     matrix
         A new matrix whose entries are random floats chosen uniformly from
-        the interval [-RANDOM_MAX, RANDOM_MAX].
+        the interval ``[-RANDOM_MAX, RANDOM_MAX]``.
 
     Examples
     --------
@@ -263,7 +267,7 @@ def random_lyapunov_like_icecream(dims):
     matrix
         A new matrix, Lyapunov-like on the ice-cream cone in ``dims``
         dimensions, whose free entries are random floats chosen uniformly
-        from the interval [-RANDOM_MAX, RANDOM_MAX].
+        from the interval ``[-RANDOM_MAX, RANDOM_MAX]``.
 
     References
     ----------
@@ -297,12 +301,19 @@ def random_lyapunov_like_icecream(dims):
 
 def random_orthant_game():
     """
-    Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
-    random game over the nonnegative orthant, and return the
-    corresponding :class:`SymmetricLinearGame`.
+    Generate a random game over the nonnegative orthant.
+
+    We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within
+    the constraints of the nonnegative orthant, and then construct a
+    game from them. The process is repeated until we generate a game with
+    a condition number under ``MAX_COND``.
+
+    Returns
+    -------
+
+    SymmetricLinearGame
+        A random game over some nonnegative orthant.
 
-    We keep going until we generate a game with a condition number under
-    MAX_COND.
     """
     ambient_dim = random_natural() + 1
     K = NonnegativeOrthant(ambient_dim)
@@ -319,12 +330,19 @@ def random_orthant_game():
 
 def random_icecream_game():
     """
-    Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
-    random game over the ice-cream cone, and return the corresponding
-    :class:`SymmetricLinearGame`.
+    Generate a random game over the ice-cream cone.
+
+    We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within
+    the constraints of the ice-cream cone, and then construct a game
+    from them. The process is repeated until we generate a game with a
+    condition number under ``MAX_COND``.
+
+    Returns
+    -------
+
+    SymmetricLinearGame
+        A random game over some ice-cream cone.
 
-    We keep going until we generate a game with a condition number under
-    MAX_COND.
     """
     # Use a minimum dimension of two to avoid divide-by-zero in
     # the fudge factor we make up later.
@@ -361,6 +379,14 @@ def random_ll_orthant_game():
     things are Lyapunov-like on the nonnegative orthant. That process is
     repeated until the condition number of the resulting game is within
     ``MAX_COND``.
+
+    Returns
+    -------
+
+    SymmetricLinearGame
+        A random game over some nonnegative orthant whose ``payoff`` method
+        is based on a Lyapunov-like ``L`` operator.
+
     """
     G = random_orthant_game()
     L = random_diagonal_matrix(G._K.dimension())
@@ -385,6 +411,14 @@ def random_ll_icecream_game():
     to have a :func:`random_lyapunov_like_icecream` operator. That
     process is repeated until the condition number of the resulting game
     is within ``MAX_COND``.
+
+    Returns
+    -------
+
+    SymmetricLinearGame
+        A random game over some ice-cream cone whose ``payoff`` method
+        is based on a Lyapunov-like ``L`` operator.
+
     """
     G = random_icecream_game()
     L = random_lyapunov_like_icecream(G._K.dimension())
@@ -410,6 +444,14 @@ def random_positive_orthant_game():
     to have a :func:`random_nonnegative_matrix` as its operator. That
     process is repeated until the condition number of the resulting game
     is within ``MAX_COND``.
+
+    Returns
+    -------
+
+    SymmetricLinearGame
+        A random game over some nonnegative orthant whose ``payoff`` method
+        is based on a positive ``L`` operator.
+
     """
 
     G = random_orthant_game()
@@ -431,15 +473,18 @@ def random_nn_scaling(G):
     """
     Scale the given game by a random nonnegative amount.
 
+    We re-attempt the scaling with a new random number until the
+    resulting scaled game has an acceptable condition number.
+
     Parameters
     ----------
 
-    G : :class:`SymmetricLinearGame`
+    G : SymmetricLinearGame
         The game that you would like to scale.
 
     Returns
     -------
-    (float, :class:`SymmetricLinearGame`)
+    (float, SymmetricLinearGame)
         A pair containing the both the scaling factor and the new scaled game.
 
     """
@@ -458,15 +503,18 @@ def random_translation(G):
     """
     Translate the given game by a random amount.
 
+    We re-attempt the translation with new random scalars until the
+    resulting translated game has an acceptable condition number.
+
     Parameters
     ----------
 
-    G : :class:`SymmetricLinearGame`
+    G : SymmetricLinearGame
         The game that you would like to translate.
 
     Returns
     -------
-    (float, :class:`SymmetricLinearGame`)
+    (float, SymmetricLinearGame)
         A pair containing the both the translation distance and the new
         scaled game.