DOC: unambiguous np.histogram dtype description (#25520)

hmeine · web-flow · commit 448e4dabb5e7 · 2024-01-16T16:10:53.000-08:00
* DOC: unambiguous np.histogram dtype description As a follow-up of #25403, let's be more specific than "dictates the dtype" because that could still mean that there is a mapping applied such as weights uint8 -> acc uint64, weights float -> acc double, ... That would make so much sense that people could expect that and thus read it into the documentation, I am afraid.
diff --git a/numpy/lib/_histograms_impl.py b/numpy/lib/_histograms_impl.py
@@ -711,8 +711,9 @@ def histogram(a, bins=10, range=None, density=None, weights=None):
         (instead of 1). If `density` is True, the weights are
         normalized, so that the integral of the density over the range
         remains 1.
-        Please note that the ``dtype`` of `weights` will dictate the
-        ``dtype`` of the returned accumulator (`hist`).
+        Please note that the ``dtype`` of `weights` will also become the
+        ``dtype`` of the returned accumulator (`hist`), so it must be
+        large enough to hold accumulated values as well.
     density : bool, optional
         If ``False``, the result will contain the number of samples in
         each bin. If ``True``, the result is the value of the
@@ -725,7 +726,8 @@ def histogram(a, bins=10, range=None, density=None, weights=None):
     -------
     hist : array
         The values of the histogram. See `density` and `weights` for a
-        description of the possible semantics.
+        description of the possible semantics.  If `weights` are given,
+        ``hist.dtype`` will be taken from `weights`.
     bin_edges : array of dtype float
         Return the bin edges ``(length(hist)+1)``.
 
