API, DOC: change names to multivariate_hypergeometric, improve docs

6 files changed, 22 insertions, 32 deletions

diff --git a/doc/source/reference/random/c-api.rst b/doc/source/reference/random/c-api.rst
index 2a9de04dc..0d60f4d9e 100644
--- a/doc/source/reference/random/c-api.rst
+++ b/doc/source/reference/random/c-api.rst
@@ -3,25 +3,15 @@ Cython API for random
 
 .. currentmodule:: numpy.random
 
-Typed versions of many of the `Generator` and `BitGenerator` methods can be
-accessed directly from Cython: the complete list is given below.
+Typed versions of many of the `Generator` and `BitGenerator` methods as well as
+the classes themselves can be accessed directly from Cython via
 
-The ``_bit_generator`` module is usable via::
+.. code-block:: cython
 
-    cimport numpy.random._bit_generator
-
-It provides function pointers for quickly accessing the next bytes in the
-`BitGenerator` via a :c:type:`bitgen_t` struct.
-
-The ``_generator`` module is usable via::
-
-    cimport numpy.random._generator
-
-It provides low-level functions for various distributions. All the functions
-require a ``bitgen_t`` BitGenerator structure.
+    cimport numpy.random
 
 C API for random
----------------------
+----------------
 
 Access to various distributions is available via Cython or C-wrapper libraries
 like CFFI. All the functions accept a :c:type:`bitgen_t` as their first argument.
@@ -180,9 +170,9 @@ The functions are named with the following conventions:
 
 .. c:function:: void random_multinomial(bitgen_t *bitgen_state, npy_int64 n, npy_int64 *mnix, double *pix, npy_intp d, binomial_t *binomial)
 
-.. c:function:: int random_mvhg_count(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
+.. c:function:: int random_multivariate_hypergeometric_count(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
 
-.. c:function:: void random_mvhg_marginals(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
+.. c:function:: void random_multivariate_hypergeometric_marginals(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
 
 Generate a single integer
 
diff --git a/doc/source/reference/random/extending.rst b/doc/source/reference/random/extending.rst
index 12311379d..442102caa 100644
--- a/doc/source/reference/random/extending.rst
+++ b/doc/source/reference/random/extending.rst
@@ -49,7 +49,7 @@ RNG structure.
     :start-after: example 2
 
 These functions along with a minimal setup file are included in the
-`examples` folder, ``numpy.random.examples``.
+`examples` folder, ``numpy.random._examples``.
 
 CFFI
 ====
diff --git a/numpy/core/include/numpy/random/distributions.h b/numpy/core/include/numpy/random/distributions.h
index 0e69fc508..c474c4d14 100644
--- a/numpy/core/include/numpy/random/distributions.h
+++ b/numpy/core/include/numpy/random/distributions.h
@@ -169,14 +169,14 @@ DECLDIR void random_multinomial(bitgen_t *bitgen_state, RAND_INT_TYPE n, RAND_IN
                                 double *pix, npy_intp d, binomial_t *binomial);
 
 /* multivariate hypergeometric, "count" method */
-DECLDIR int random_mvhg_count(bitgen_t *bitgen_state,
+DECLDIR int random_multivariate_hypergeometric_count(bitgen_t *bitgen_state,
                               int64_t total,
                               size_t num_colors, int64_t *colors,
                               int64_t nsample,
                               size_t num_variates, int64_t *variates);
 
 /* multivariate hypergeometric, "marginals" method */
-DECLDIR void random_mvhg_marginals(bitgen_t *bitgen_state,
+DECLDIR void random_multivariate_hypergeometric_marginals(bitgen_t *bitgen_state,
                                    int64_t total,
                                    size_t num_colors, int64_t *colors,
                                    int64_t nsample,
diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx
index 74b379da8..d76cde44c 100644
--- a/numpy/random/_generator.pyx
+++ b/numpy/random/_generator.pyx
@@ -124,12 +124,12 @@ cdef extern from "numpy/random/distributions.h":
     void random_multinomial(bitgen_t *bitgen_state, int64_t n, int64_t *mnix,
                             double *pix, np.npy_intp d, binomial_t *binomial) nogil
 
-    int random_mvhg_count(bitgen_t *bitgen_state,
+    int random_multivariate_hypergeometric_count(bitgen_t *bitgen_state,
                           int64_t total,
                           size_t num_colors, int64_t *colors,
                           int64_t nsample,
                           size_t num_variates, int64_t *variates) nogil
-    void random_mvhg_marginals(bitgen_t *bitgen_state,
+    void random_multivariate_hypergeometric_marginals(bitgen_t *bitgen_state,
                                int64_t total,
                                size_t num_colors, int64_t *colors,
                                int64_t nsample,
@@ -4010,18 +4010,18 @@ cdef class Generator:
 
         if method == 'count':
             with self.lock, nogil:
-                result = random_mvhg_count(&self._bitgen, total,
-                                           num_colors, colors_ptr, nsamp,
-                                           num_variates, variates_ptr)
+                result = random_multivariate_hypergeometric_count(&self._bitgen,
+                                        total, num_colors, colors_ptr, nsamp,
+                                        num_variates, variates_ptr)
             if result == -1:
                 raise MemoryError("Insufficent memory for multivariate_"
                                   "hypergeometric with method='count' and "
                                   "sum(colors)=%d" % total)
         else:
             with self.lock, nogil:
-                random_mvhg_marginals(&self._bitgen, total,
-                                      num_colors, colors_ptr, nsamp,
-                                      num_variates, variates_ptr)
+                random_multivariate_hypergeometric_marginals(&self._bitgen,
+                                        total, num_colors, colors_ptr, nsamp,
+                                        num_variates, variates_ptr)
         return variates
 
     def dirichlet(self, object alpha, size=None):
diff --git a/numpy/random/src/distributions/random_mvhg_count.c b/numpy/random/src/distributions/random_mvhg_count.c
index 0c46ea417..7cbed1f9e 100644
--- a/numpy/random/src/distributions/random_mvhg_count.c
+++ b/numpy/random/src/distributions/random_mvhg_count.c
@@ -5,7 +5,7 @@
 #include "numpy/random/distributions.h"
 
 /*
- *  random_mvhg_count
+ *  random_multivariate_hypergeometric_count
  *
  *  Draw variates from the multivariate hypergeometric distribution--
  *  the "count" algorithm.
@@ -57,7 +57,7 @@
  *    *  the product num_variates * num_colors does not overflow
  */
 
-int random_mvhg_count(bitgen_t *bitgen_state,
+int random_multivariate_hypergeometric_count(bitgen_t *bitgen_state,
                       int64_t total,
                       size_t num_colors, int64_t *colors,
                       int64_t nsample,
diff --git a/numpy/random/src/distributions/random_mvhg_marginals.c b/numpy/random/src/distributions/random_mvhg_marginals.c
index 7e4c24988..809d129de 100644
--- a/numpy/random/src/distributions/random_mvhg_marginals.c
+++ b/numpy/random/src/distributions/random_mvhg_marginals.c
@@ -8,7 +8,7 @@
 
 
 /*
- *  random_mvhg_marginals
+ *  random_multivariate_hypergeometric_marginals
  *
  *  Draw samples from the multivariate hypergeometric distribution--
  *  the "marginals" algorithm.
@@ -95,7 +95,7 @@
  *    *  the product num_variates * num_colors does not overflow
  */
 
-void random_mvhg_marginals(bitgen_t *bitgen_state,
+void random_multivariate_hypergeometric_marginals(bitgen_t *bitgen_state,
                            int64_t total,
                            size_t num_colors, int64_t *colors,
                            int64_t nsample,