Repository: numpy/numpy

Issue:
Consistency of docstrings between `ones`, `zeros` and `empty`.
There is some inconsistency in docstrings for 3 frequently used constructor functions:

* `ones`
* `zeros`
* `empty`

1. The docstring for `ones` looks as follows:
```python
ones(shape, dtype=None, order='C'):
    """
    Return a new array of given shape and type, filled with ones.

    Parameters
    ----------
    shape : int or sequence of ints
        Shape of the new array, e.g., ``(2, 3)`` or ``2``.
    dtype : data-type, optional
        The desired data-type for the array, e.g., `numpy.int8`.  Default is
        `numpy.float64`.
    order : {'C', 'F'}, optional
        Whether to store multidimensional data in C- or Fortran-contiguous
        (row- or column-wise) order in memory.
```
Interesting part here is signature `ones(shape, dtype=None, order='C')`, and `dtype=None`. While  `dtype` description it is said that "Default is `numpy.float64`". For other two functions the signatures are:

    zeros(shape, dtype=float, order='C')
    empty(shape, dtype=float, order='C')

While they are better, they are also incorrect -> should be `dtype=double` or `dtype=float64`.

2. The description of parameters for `ones` and `zeros` a pretty identical. But for the `empty` it is somewhat stripped down:

```python
Docstring:
empty(shape, dtype=float, order='C')

Return a new array of given shape and type, without initializing entries.

Parameters
----------
shape : int or tuple of int
    Shape of the empty array
dtype : data-type, optional
    Desired output data-type.
order : {'C', 'F'}, optional
    Whether to store multi-dimensional data in row-major
    (C-style) or column-major (Fortran-style) order in
    memory.
```


Discussion:
While this is offtopic, but somewhat related, the chosen default type for these functions - `float64` for `dtype` is the very general type with all consequences see the #10405.
> While they are better, they are also incorrect 

No, they are correct - numpy promotes float into `np.double`/`np.float64`. Calling `np.ones(..., dtype=float)` is always the same as `np.ones(...)`.

Your other remarks are valid - patch welcome!

Resolving patch:
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -845,10 +845,11 @@ def luf(lamdaexpr, *args, **kwargs):
     Parameters
     ----------
     shape : int or tuple of int
-        Shape of the empty array
+        Shape of the empty array, e.g., ``(2, 3)`` or ``2``.
     dtype : data-type, optional
-        Desired output data-type.
-    order : {'C', 'F'}, optional
+        Desired output data-type for the array, e.g, `numpy.int8`. Default is
+        `numpy.float64`.
+    order : {'C', 'F'}, optional, default: 'C'
         Whether to store multi-dimensional data in row-major
         (C-style) or column-major (Fortran-style) order in
         memory.
@@ -965,14 +966,15 @@ def luf(lamdaexpr, *args, **kwargs):
 
     Parameters
     ----------
-    shape : int or sequence of ints
+    shape : int or tuple of ints
         Shape of the new array, e.g., ``(2, 3)`` or ``2``.
     dtype : data-type, optional
         The desired data-type for the array, e.g., `numpy.int8`.  Default is
         `numpy.float64`.
-    order : {'C', 'F'}, optional
-        Whether to store multidimensional data in C- or Fortran-contiguous
-        (row- or column-wise) order in memory.
+    order : {'C', 'F'}, optional, default: 'C'
+        Whether to store multi-dimensional data in row-major
+        (C-style) or column-major (Fortran-style) order in
+        memory.
 
     Returns
     -------
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -160,9 +160,10 @@ def ones(shape, dtype=None, order='C'):
     dtype : data-type, optional
         The desired data-type for the array, e.g., `numpy.int8`.  Default is
         `numpy.float64`.
-    order : {'C', 'F'}, optional
-        Whether to store multidimensional data in C- or Fortran-contiguous
-        (row- or column-wise) order in memory.
+    order : {'C', 'F'}, optional, default: C
+        Whether to store multi-dimensional data in row-major
+        (C-style) or column-major (Fortran-style) order in
+        memory.
 
     Returns
     -------


Test patch: