Repository: numpy/numpy

Issue:
DOC: Update language on numpy.squeeze
In the [numpy.squeeze](https://numpy.org/doc/stable/reference/generated/numpy.squeeze.html) docstring, the use of "single-dimensional" and "singleton dimensions" (in the reference to numpy.expand_dims) is a bit confusing. This could be improved by using "one-dimensional" instead or rewording the docstring.




Discussion:
I agree. Also, I looked for a glossary definition of "singleton dimension" and could not find it. If we are going to stick with this term, we need to define it somewhere in the docs.
I would be happy to avoid the term entirely.  There do not really seem to be many places where its used in the docs (a grep found 2, plus a few commit messages/code comments).
If we need such a term, then it would make sense in the broadcasting documentation.  While "dimension of size one" feels a bit long, I honestly do not think "singleton" has the right connotation to begin with.

EDIT: Yeah, "length one" is better.
I am a newbie, so I did not know how prevalent was the term. If it occurs only twice, it doesn't deserve it's own jargon entry, in my opinion. I like "dimension of size one" or "dimension of length one" like @melissawm tweeted.
@melissawm and @seberg, I would like to work on this issue. 
Do I need to change all these files: [numpy/core/fromnumeric.py](https://github.com/numpy/numpy/blob/master/numpy/core/fromnumeric.py#L1450),  [numpy/core/_add_newdocs.py](https://github.com/numpy/numpy/blob/master/numpy/core/_add_newdocs.py#L3754) and [numpy/matrixlib/defmatrix.py](https://github.com/numpy/numpy/blob/master/numpy/matrixlib/defmatrix.py#L332) or only [numpy/core/fromnumeric.py](https://github.com/numpy/numpy/blob/master/numpy/core/fromnumeric.py#L1450)?
@ruppysuppy: Changing all of those sounds good to me :)

Resolving patch:
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -3751,7 +3751,7 @@
     """
     a.squeeze(axis=None)
 
-    Remove single-dimensional entries from the shape of `a`.
+    Remove axes of length one from `a`.
 
     Refer to `numpy.squeeze` for full documentation.
 
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1434,7 +1434,7 @@ def _squeeze_dispatcher(a, axis=None):
 @array_function_dispatch(_squeeze_dispatcher)
 def squeeze(a, axis=None):
     """
-    Remove single-dimensional entries from the shape of an array.
+    Remove axes of length one from `a`.
 
     Parameters
     ----------
@@ -1443,7 +1443,7 @@ def squeeze(a, axis=None):
     axis : None or int or tuple of ints, optional
         .. versionadded:: 1.7.0
 
-        Selects a subset of the single-dimensional entries in the
+        Selects a subset of the entries of length one in the
         shape. If an axis is selected with shape entry greater than
         one, an error is raised.
 
@@ -1462,7 +1462,7 @@ def squeeze(a, axis=None):
 
     See Also
     --------
-    expand_dims : The inverse operation, adding singleton dimensions
+    expand_dims : The inverse operation, adding entries of length one
     reshape : Insert, remove, and combine dimensions, and resize existing ones
 
     Examples
diff --git a/numpy/matrixlib/defmatrix.py b/numpy/matrixlib/defmatrix.py
--- a/numpy/matrixlib/defmatrix.py
+++ b/numpy/matrixlib/defmatrix.py
@@ -329,7 +329,7 @@ def squeeze(self, axis=None):
         Parameters
         ----------
         axis : None or int or tuple of ints, optional
-            Selects a subset of the single-dimensional entries in the shape.
+            Selects a subset of the axes of length one in the shape.
             If an axis is selected with shape entry greater than one,
             an error is raised.
 


Test patch: