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

diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index a702b2463c39b1678801723dbe2698d3d3105361..00c0b539edce954a551d1314087b56847c36f002 100644 (file)
--- 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