Add "description" attribute to Value.

tools/telemetry/telemetry/value/__init__.py

 # Copyright 2013 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.
 """
 The Value hierarchy provides a way of representing the values measurements
 produce such that they can be merged across runs, grouped by page, and output
 to different targets.
 
 The core Value concept provides the basic functionality:
 - association with a page, may be none
 - naming and units
 - importance tracking [whether a value will show up on a waterfall or output
   file by default]
+- other metadata, such as a description of what was measured
 - default conversion to scalar and string
 - merging properties
 
 A page may actually run a few times during a single telemetry session.
 Downstream consumers of test results typically want to group these runs
 together, then compute summary statistics across runs. Value provides the
 Merge* family of methods for this kind of aggregation.
 """
 
 # When combining a pair of Values togehter, it is sometimes ambiguous whether
 # the values should be concatenated, or one should be picked as representative.
 # The possible merging policies are listed here.
 CONCATENATE = 'concatenate'
 PICK_FIRST = 'pick-first'
 
 # When converting a Value to its buildbot equivalent, the context in which the
 # value is being interpreted actually affects the conversion. This is insane,
 # but there you have it. There are three contexts in which Values are converted
 # for use by buildbot, represented by these output-intent values.
 PER_PAGE_RESULT_OUTPUT_CONTEXT = 'per-page-result-output-context'
 COMPUTED_PER_PAGE_SUMMARY_OUTPUT_CONTEXT = 'merged-pages-result-output-context'
 SUMMARY_RESULT_OUTPUT_CONTEXT = 'summary-result-output-context'
 
 class Value(object):
   """An abstract value produced by a telemetry page test.
   """
-  def __init__(self, page, name, units, important):
+  def __init__(self, page, name, units, important, description):
     """A generic Value object.
 
-    Note: page may be given as None to indicate that the value represents
-    results multiple pages.
+    Args:
+      page: A Page object, may be given as None to indicate that the value
+          represents results for multiple pages.
+      name: A value name string, may contain a dot. Values from the same test
+          with the same prefix before the dot may be considered to belong to
+          the same chart.
+      units: A units string.
+      important: Whether the value is "important". Causes the value to appear
+          by default in downstream UIs.
+      description: A string explaining in human-understandable terms what this
+          value represents.
     """
     self.page = page
     self.name = name
     self.units = units
     self.important = important
+    self.description = description
 
   def IsMergableWith(self, that):
     return (self.units == that.units and
             type(self) == type(that) and
             self.important == that.important)
 
   @classmethod
   def MergeLikeValuesFromSamePage(cls, values):
     """Combines the provided list of values into a single compound value.
 
@@ skipping 101 matching lines @@
     """
     return self._AsDictImpl()
 
   def _AsDictImpl(self):
     d = {
       'name': self.name,
       'type': self.GetJSONTypeName(),
       'unit': self.units,
     }
 
+    if self.description:
+      d['description'] = self.description
+
     if self.page:
       d['page_id'] = self.page.id
 
     return d
 
   def AsDictWithoutBaseClassEntries(self):
     full_dict = self.AsDict()
     base_dict_keys = set(self._AsDictImpl().keys())
 
-    # Exctracts only entries added by the subclass.
+    # Extracts only entries added by the subclass.
     return dict([(k, v) for (k, v) in full_dict.iteritems()
                   if k not in base_dict_keys])
 
 def ValueNameFromTraceAndChartName(trace_name, chart_name=None):
   """Mangles a trace name plus optional chart name into a standard string.
 
   A value might just be a bareword name, e.g. numPixels. In that case, its
   chart may be None.
 
   But, a value might also be intended for display with other values, in which
@@ skipping 15 matching lines @@
   whereas telemetry represents values with a chart_name.trace_name convention,
   where chart_name is optional.
 
   This converts from the telemetry convention to the buildbot convention,
   returning a 2-tuple (measurement_name, trace_name).
   """
   if '.' in value_name:
     return value_name.split('.', 1)
   else:
     return value_name, value_name