Update libmetrics docs to cover some recent questions and issues.

metrics_library.h

 // Copyright (c) 2010 The Chromium OS 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 METRICS_LIBRARY_H_
 #define METRICS_LIBRARY_H_
 
 #include <sys/types.h>
 #include <string>
 
@@ skipping 20 matching lines @@
   // true on success. This method results in the equivalent of an
   // asynchronous non-blocking RPC to UMA_HISTOGRAM_CUSTOM_COUNTS
   // inside Chrome (see base/histogram.h).
   //
   // |sample| is the sample value to be recorded (|min| <= |sample| < |max|).
   // |min| is the minimum value of the histogram samples (|min| > 0).
   // |max| is the maximum value of the histogram samples.
   // |nbuckets| is the number of histogram buckets.
   // [0,min) is the implicit underflow bucket.
   // [|max|,infinity) is the implicit overflow bucket.
+  //
+  // Note that the memory allocated in Chrome for each histogram is
+  // proportional to the number of buckets. Therefore, it is strongly
+  // recommended to keep this number low (e.g., 50 is normal, while
+  // 100 is high).
   bool SendToUMA(const std::string& name, int sample,
                  int min, int max, int nbuckets);
 
   // Sends linear histogram data to Chrome for transport to UMA and
   // returns true on success. This method results in the equivalent of
   // an asynchronous non-blocking RPC to UMA_HISTOGRAM_ENUMERATION
   // inside Chrome (see base/histogram.h).
   //
   // |sample| is the sample value to be recorded (1 <= |sample| < |max|).
   // |max| is the maximum value of the histogram samples.
   // 0 is the implicit underflow bucket.
   // [|max|,infinity) is the implicit overflow bucket.
+  //
+  // An enumaration histogram requires |max| + 1 number of
+  // buckets. Note that the memory allocated in Chrome for each
+  // histogram is proportional to the number of buckets. Therefore, it
+  // is strongly recommended to keep this number low (e.g., 50 is
+  // normal, while 100 is high).
   bool SendEnumToUMA(const std::string& name, int sample, int max);
 
   // Sends to Autotest and returns true on success.
   static bool SendToAutotest(const std::string& name, int value);
 
  private:
   friend class CMetricsLibraryTest;
   friend class MetricsLibraryTest;
   FRIEND_TEST(MetricsLibraryTest, FormatChromeMessage);
   FRIEND_TEST(MetricsLibraryTest, FormatChromeMessageTooLong);
@@ skipping 12 matching lines @@
   // The arbitrary |format| argument covers the non-LENGTH portion of the
   // message. The caller is responsible to store the \0 character
   // between NAME and VALUE (e.g. "%s%c%d", name, '\0', value).
   int32_t FormatChromeMessage(int32_t buffer_size, char* buffer,
                               const char* format, ...);
 
   const char* uma_events_file_;
 };
 
 #endif  // METRICS_LIBRARY_H_