[Cleanup] Clarify a histogram macro comment.

base/metrics/histogram_macros_internal.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_
 #define BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_
 
 #include "base/atomicops.h"
 #include "base/logging.h"
 #include "base/metrics/histogram.h"
@@ skipping 78 matching lines @@
   } while (0)
 
 // This is a helper macro used by other macros and shouldn't be used directly.
 #define INTERNAL_HISTOGRAM_CUSTOM_COUNTS_WITH_FLAG(name, sample, min, max,     \
                                                    bucket_count, flag)         \
     STATIC_HISTOGRAM_POINTER_BLOCK(                                            \
         name, Add(sample),                                                     \
         base::Histogram::FactoryGet(name, min, max, bucket_count, flag))
 
 // This is a helper macro used by other macros and shouldn't be used directly.
-// One additional bucket is created in the LinearHistogram for the illegal
-// values >= boundary_value so that mistakes in calling the UMA enumeration
-// macros can be detected.
+// For an enumeration with N items, recording values in the range [0, N - 1],
+// this macro creates a linear histogram with N + 1 buckets:
+//   [0, 1), [1, 2), ..., [N - 1, N), and an overflow bucket [N, infinity).
+// Code should never emit to the overflow bucket; only to the other N buckets.
+// This allows future versions of Chrome to safely append new entries to the
+// enumeration. Otherwise, the histogram would have [N - 1, infinity) as its
+// overflow bucket, and so the maximal value (N - 1) would be emitted to this
+// overflow bucket. But, if an additional enumerated value were later added, the
+// bucket label for the value (N - 1) would change to [N - 1, N), which would
+// result in different versions of Chrome using different bucket labels for
+// identical data.
 #define INTERNAL_HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary, flag) \
   do {                                                                         \
     static_assert(                                                             \
         !std::is_enum<decltype(sample)>::value ||                              \
             !std::is_enum<decltype(boundary)>::value ||                        \
             std::is_same<std::remove_const<decltype(sample)>::type,            \
                          std::remove_const<decltype(boundary)>::type>::value,  \
         "|sample| and |boundary| shouldn't be of different enums");            \
     STATIC_HISTOGRAM_POINTER_BLOCK(                                            \
         name, Add(sample), base::LinearHistogram::FactoryGet(                  \
@@ skipping 28 matching lines @@
 // may be more efficient in memory if the total number of sample values is small
 // compared to the range of their values.
 #define INTERNAL_HISTOGRAM_SPARSE_SLOWLY(name, sample)                         \
     do {                                                                       \
       base::HistogramBase* histogram = base::SparseHistogram::FactoryGet(      \
           name, base::HistogramBase::kUmaTargetedHistogramFlag);               \
       histogram->Add(sample);                                                  \
     } while (0)
 
 #endif  // BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_