Expand the inline documentation for the HISTOGRAM_ENUMERATION macros.
This should help to reduce confusion about the recommended upper- and lower-bounds for enumerated histograms.
BUG=none
TEST=none
Review URL: http://codereview.chromium.org/8273022
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@105440 0039d316-1c4b-4281-b951-d872f2087c98
CrOS-Libchrome-Original-Commit: c340bf4185b0cfba66eae8299fce69741553e335
diff --git a/base/metrics/histogram.h b/base/metrics/histogram.h
index 7a73f96..401ece7 100644
--- a/base/metrics/histogram.h
+++ b/base/metrics/histogram.h
@@ -163,7 +163,11 @@
base::Histogram::kNoFlags))
// Support histograming of an enumerated value. The samples should always be
-// less than boundary_value.
+// strictly less than |boundary_value| -- this prevents you from running into
+// problems down the line if you add additional buckets to the histogram. Note
+// also that, despite explicitly setting the minimum bucket value to |1| below,
+// it is fine for enumerated histograms to be 0-indexed -- this is because
+// enumerated histograms should never have underflow.
#define HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
@@ -266,6 +270,8 @@
base::BooleanHistogram::FactoryGet(name, \
base::Histogram::kUmaTargetedHistogramFlag))
+// The samples should always be strictly less than |boundary_value|. For more
+// details, see the comment for the |HISTOGRAM_ENUMERATION| macro, above.
#define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
base::LinearHistogram::FactoryGet(name, 1, boundary_value, \