DOC: Mention we can return unitinitialized values (#11086)

* DOC: mention we can return unitinitialized values

* squash and rebase, extend explanation and improve docstring template

* MAINT: Spelling fixes for docstrings.

[ci skip]

* MAINT: Update following feedback.

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index 59d25a9ca..bebd047f6 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -327,6 +327,13 @@ advanced usage and will not typically be used.
     multiple outputs is deprecated, and will raise a warning in numpy 1.10,
     and an error in a future release.
 
+    If 'out' is None (the default), a uninitialized return array is created.
+    The output array is then filled with the results of the ufunc in the places
+    that the broadcast 'where' is True. If 'where' is the scalar True (the
+    default), then this corresponds to the entire output being filled.
+    Note that outputs not explicitly filled are left with their
+    uninitialized values.
+
 *where*
 
     .. versionadded:: 1.7
@@ -336,6 +343,9 @@ advanced usage and will not typically be used.
     of False indicate to leave the value in the output alone. This argument
     cannot be used for generalized ufuncs as those take non-scalar input.
 
+    Note that if an uninitialized return array is created, values of False
+    will leave those values **uninitialized**.
+
 *axes*
 
     .. versionadded:: 1.15