Repository: numpy/numpy

Issue:
DOC The docstring of numpy.equal is misleading
The [docstring of numpy.equal](https://www.numpy.org/devdocs/reference/generated/numpy.equal.html#numpy-equal) says that the input arrays should be of the same shape. I think this is wrong as broadcasting will be used and no error is returned if you use two input arrays with different shapes.

Besides the second example does not compare two arrays.
```python
>>> np.equal(1, np.ones(1))
array([ True])
```


Discussion:
PR welcome. The text comes from `numpy.core._add_newdoc('numpy.core.umath', 'equal'), around line 1068 in `numpy/core/_add_newdocs.py` 

To view the changes, you need to [build the documentation](https://www.numpy.org/devdocs/docs/howto_build_docs.html), I find the easiest way to do this is to create a virtualenv, activate it, then from the top level numpy directory
```
pip install .
(cd doc; make html)
```
The first time you do this, the documentation creation takes quite a while.

Resolving patch:
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -32,6 +32,9 @@ def get(name):
             For other keyword-only arguments, see the
             :ref:`ufunc docs <ufuncs.kwargs>`.
     """).strip(),
+    'BROADCASTABLE_2': ("If ``x1.shape != x2.shape``, they must be "
+                        "broadcastable to a common shape (which becomes the "
+                        "shape of the output)."),
     'OUT_SCALAR_1': "This is a scalar if `x` is a scalar.",
     'OUT_SCALAR_2': "This is a scalar if both `x1` and `x2` are scalars.",
 }
@@ -103,9 +106,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays to be added.  If ``x1.shape != x2.shape``, they must be
-        broadcastable to a common shape (which may be the shape of one or
-        the other).
+        The arrays to be added. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -431,8 +432,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like, real-valued
         `y`-coordinates.
     x2 : array_like, real-valued
-        `x`-coordinates. `x2` must be broadcastable to match the shape of
-        `x1` or vice versa.
+        `x`-coordinates. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -555,7 +555,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Only integer and boolean types are handled.
+        Only integer and boolean types are handled. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -608,7 +608,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Only integer and boolean types are handled.
+        Only integer and boolean types are handled. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -666,7 +666,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Only integer and boolean types are handled.
+        Only integer and boolean types are handled. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -968,7 +968,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Input values.
     x2 : array_like
-        The value of the function when x1 is 0.
+        The value of the function when x1 is 0. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1003,7 +1003,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Dividend array.
     x2 : array_like
-        Divisor array.
+        Divisor array. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1072,7 +1072,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays of the same shape.
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1319,7 +1319,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Numerator.
     x2 : array_like
-        Denominator.
+        Denominator. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1359,7 +1359,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Dividend.
     x2 : array_like
-        Divisor.
+        Divisor. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1409,9 +1409,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays.  If ``x1.shape != x2.shape``, they must be
-        broadcastable to a common shape (which may be the shape of one or
-        the other).
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1447,9 +1445,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays.  If ``x1.shape != x2.shape``, they must be
-        broadcastable to a common shape (which may be the shape of one or
-        the other).
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1482,7 +1478,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Leg of the triangle(s).
+        Leg of the triangle(s). $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1783,6 +1779,7 @@ def add_newdoc(place, name, doc):
         Input values.
     x2 : array_like of integer type
         Number of zeros to append to `x1`. Has to be non-negative.
+        $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1818,9 +1815,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays.  If ``x1.shape != x2.shape``, they must be
-        broadcastable to a common shape (which may be the shape of one or
-        the other).
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -1848,9 +1843,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays.  If ``x1.shape != x2.shape``, they must be
-        broadcastable to a common shape (which may be the shape of one or
-        the other).
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2034,7 +2027,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input values.
+        Input values. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2076,7 +2069,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input values.
+        Input values. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2167,14 +2160,14 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays. `x1` and `x2` must be of the same shape.
+        Input arrays. $BROADCASTABLE_2
     $PARAMS
 
     Returns
     -------
     y : ndarray or bool
-        Boolean result with the same shape as `x1` and `x2` of the logical
-        AND operation on corresponding elements of `x1` and `x2`.
+        Boolean result of the logical OR operation applied to the elements
+        of `x1` and `x2`; the shape is determined by broadcasting.
         $OUT_SCALAR_2
 
     See Also
@@ -2237,14 +2230,14 @@ def add_newdoc(place, name, doc):
     ----------
     x1, x2 : array_like
         Logical OR is applied to the elements of `x1` and `x2`.
-        They have to be of the same shape.
+        $BROADCASTABLE_2
     $PARAMS
 
     Returns
     -------
     y : ndarray or bool
-        Boolean result with the same shape as `x1` and `x2` of the logical
-        OR operation on elements of `x1` and `x2`.
+        Boolean result of the logical OR operation applied to the elements
+        of `x1` and `x2`; the shape is determined by broadcasting.
         $OUT_SCALAR_2
 
     See Also
@@ -2272,16 +2265,14 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Logical XOR is applied to the elements of `x1` and `x2`.  They must
-        be broadcastable to the same shape.
+        Logical XOR is applied to the elements of `x1` and `x2`. $BROADCASTABLE_2
     $PARAMS
 
     Returns
     -------
     y : bool or ndarray of bool
         Boolean result of the logical XOR operation applied to the elements
-        of `x1` and `x2`; the shape is determined by whether or not
-        broadcasting of one or both arrays was required.
+        of `x1` and `x2`; the shape is determined by broadcasting.
         $OUT_SCALAR_2
 
     See Also
@@ -2321,8 +2312,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays holding the elements to be compared. They must have
-        the same shape, or shapes that can be broadcast to a single shape.
+        The arrays holding the elements to be compared. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2380,8 +2370,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays holding the elements to be compared. They must have
-        the same shape, or shapes that can be broadcast to a single shape.
+        The arrays holding the elements to be compared. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2439,8 +2428,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays holding the elements to be compared. They must have
-        the same shape.
+        The arrays holding the elements to be compared. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2497,8 +2485,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays holding the elements to be compared. They must have
-        the same shape.
+        The arrays holding the elements to be compared. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2588,7 +2575,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays to be multiplied.
+        Input arrays to be multiplied. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2669,7 +2656,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        Input arrays.
+        Input arrays.  $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2718,7 +2705,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         The bases.
     x2 : array_like
-        The exponents.
+        The exponents. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2777,7 +2764,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         The bases.
     x2 : array_like
-        The exponents.
+        The exponents. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2949,7 +2936,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Dividend array.
     x2 : array_like
-        Divisor array.
+        Divisor array. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -2994,7 +2981,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Dividend array.
     x2 : array_like
-        Divisor array.
+        Divisor array. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3033,7 +3020,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like, int
         Input values.
     x2 : array_like, int
-        Number of bits to remove at the right of `x1`.
+        Number of bits to remove at the right of `x1`. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3160,16 +3147,14 @@ def add_newdoc(place, name, doc):
     """
     Change the sign of x1 to that of x2, element-wise.
 
-    If both arguments are arrays or sequences, they have to be of the same
-    length. If `x2` is a scalar, its sign will be copied to all elements of
-    `x1`.
+    If `x2` is a scalar, its sign will be copied to all elements of `x1`.
 
     Parameters
     ----------
     x1 : array_like
         Values to change the sign of.
     x2 : array_like
-        The sign of `x2` is copied to `x1`.
+        The sign of `x2` is copied to `x1`. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3204,6 +3189,7 @@ def add_newdoc(place, name, doc):
         Values to find the next representable value of.
     x2 : array_like
         The direction where to look for the next representable value of `x1`.
+        $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3474,7 +3460,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like
-        The arrays to be subtracted from each other.
+        The arrays to be subtracted from each other. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3613,7 +3599,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Dividend array.
     x2 : array_like
-        Divisor array.
+        Divisor array. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3712,7 +3698,7 @@ def add_newdoc(place, name, doc):
     x1 : array_like
         Array of multipliers.
     x2 : array_like, int
-        Array of twos exponents.
+        Array of twos exponents. $BROADCASTABLE_2
     $PARAMS
 
     Returns
@@ -3750,7 +3736,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like, int
-        Arrays of values
+        Arrays of values. $BROADCASTABLE_2
 
     Returns
     -------
@@ -3780,7 +3766,7 @@ def add_newdoc(place, name, doc):
     Parameters
     ----------
     x1, x2 : array_like, int
-        Arrays of values
+        Arrays of values. $BROADCASTABLE_2
 
     Returns
     -------


Test patch: