bpo-38382: Document the early-out behavior for a zero (GH-17037) (GH-17078)

miss-islington · rhettinger · rhettinger · commit 6b66dc387935 · 2019-11-06T21:58:11.000-08:00
(cherry picked from commit 7f46049) Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
@@ -164,7 +164,8 @@ However, for reading convenience, most of the examples show sorted sequences.
    The harmonic mean, sometimes called the subcontrary mean, is the
    reciprocal of the arithmetic :func:`mean` of the reciprocals of the
    data. For example, the harmonic mean of three values *a*, *b* and *c*
-   will be equivalent to ``3/(1/a + 1/b + 1/c)``.
+   will be equivalent to ``3/(1/a + 1/b + 1/c)``.  If one of the values
+   is zero, the result will be zero.
 
    The harmonic mean is a type of average, a measure of the central
    location of the data.  It is often appropriate when averaging
@@ -190,6 +191,10 @@ However, for reading convenience, most of the examples show sorted sequences.
    :exc:`StatisticsError` is raised if *data* is empty, or any element
    is less than zero.
 
+   The current algorithm has an early-out when it encounters a zero
+   in the input.  This means that the subsequent inputs are not tested
+   for validity.  (This behavior may change in the future.)
+
    .. versionadded:: 3.6
 
 
