From de968dd920eaa3d1a27877059c6bbb9043a9d26b Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Wed, 2 Mar 2022 21:21:25 +1100
Subject: [PATCH] Document that histogram() uses 256 bins per channel

---
 docs/reference/ImageStat.rst | 10 ++++++++++
 src/PIL/Image.py             | 11 ++++++-----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/reference/ImageStat.rst b/docs/reference/ImageStat.rst
index 5bb735296..f61d12313 100644
--- a/docs/reference/ImageStat.rst
+++ b/docs/reference/ImageStat.rst
@@ -14,6 +14,16 @@ for a region of an image.
     statistics. You can also pass in a previously calculated histogram.
 
     :param image: A PIL image, or a precalculated histogram.
+
+        .. note::
+
+            For a PIL image, calculations rely on the
+            :py:meth:`~PIL.Image.Image.histogram` method. The pixel counts are
+            grouped into 256 bins, even if the image has more than 8 bits per
+            channel. So ``I`` and ``F`` mode images have a maximum ``mean``,
+            ``median`` and ``rms`` of 255, and cannot have an ``extrema`` maximum
+            of more than 255.
+
     :param mask: An optional mask.
 
     .. py:attribute:: extrema
diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index c9265b5ab..4b8d2c750 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -1492,11 +1492,12 @@ class Image:
 
     def histogram(self, mask=None, extrema=None):
         """
-        Returns a histogram for the image. The histogram is returned as
-        a list of pixel counts, one for each pixel value in the source
-        image. If the image has more than one band, the histograms for
-        all bands are concatenated (for example, the histogram for an
-        "RGB" image contains 768 values).
+        Returns a histogram for the image. The histogram is returned as a
+        list of pixel counts, one for each pixel value in the source
+        image. Counts are grouped into 256 bins for each band, even if
+        the image has more than 8 bits per band. If the image has more
+        than one band, the histograms for all bands are concatenated (for
+        example, the histogram for an "RGB" image contains 768 values).
 
         A bilevel image (mode "1") is treated as a greyscale ("L") image
         by this method.