Update header documentation in opencensus/stats. (#74)

* Update header documentation in opencensus/stats.

* Update view.h

Nit.

* Clarify wording.

Author: Ian Sturdy

opencensus/stats/aggregation.h

@@ -29,7 +29,8 @@ namespace stats {
 class Aggregation final {
  public:
   // Count aggregation counts the number of records, ignoring their individual
-  // values.
+  // values. Note that 'count' measures (e.g. the count of RPCs received) should
+  // use Sum() aggregation to correctly handle non-unit recorded values.
   static Aggregation Count() {
     return Aggregation(Type::kCount, BucketBoundaries::Explicit({}));
   }
@@ -39,8 +40,9 @@ class Aggregation final {
     return Aggregation(Type::kSum, BucketBoundaries::Explicit({}));
   }
 
-  // Distribution aggregation records the number of records in each bucket
-  // defined by 'buckets', and calculates distribution stats from that.
+  // Distribution aggregation calculates distribution statistics (count, mean,
+  // range, and sum of squared deviation) and tracks a histogram of recorded
+  // values according to 'buckets'.
   static Aggregation Distribution(BucketBoundaries buckets) {
     return Aggregation(Type::kDistribution, std::move(buckets));
   }

opencensus/stats/measure_descriptor.h

@@ -33,6 +33,8 @@ class MeasureDescriptor final {
     kInt64,
   };
 
+  // See documentation on MeasureRegistry::Register*() for details of these
+  // fields.
   const std::string& name() const { return name_; }
   const std::string& units() const { return units_; }
   const std::string& description() const { return description_; }

opencensus/stats/measure_registry.h

@@ -37,7 +37,7 @@ class MeasureRegistry final {
   // registered with GetMeasure*ByName before registering it.
   //
   // 'name' should be a globally unique identifier. It is recommended that this
-  //   be in the format "<domain>/<path>", e.g. "example.com/Foo/FooUsage".
+  //   be in the format "<domain>/<path>", e.g. "example.com/client/foo_usage".
   // 'units' are the units of recorded values. The recommended grammar is:
   //     - Expression = Component { "." Component } {"/" Component }
   //     - Component = [ PREFIX ] UNIT [ Annotation ] | Annotation | "1"

opencensus/stats/stats_exporter.h

@@ -49,7 +49,9 @@ class StatsExporter final {
         const std::vector<std::pair<ViewDescriptor, ViewData>>& data) = 0;
   };
 
-  // This should only be called by push exporters' Register() methods.
+  // Registers a new handler. Every few seconds, each registered handler will be
+  // called with the present data for each registered view. This should only be
+  // called by push exporters' Register() methods.
   static void RegisterPushHandler(std::unique_ptr<Handler> handler);
 
   // Retrieves current data for all registered views, for implementing pull

opencensus/stats/view.h

@@ -22,6 +22,11 @@
 namespace opencensus {
 namespace stats {
 
+// View is an RAII handle for on-task data collection--once a View is
+// instantiated, OpenCensus will collect data for it, which can be accessed with
+// View::GetData(). To register a view for export, rather than on-task
+// collection, use ViewDescriptor::RegisterForExport() instead.
+//
 // View objects are thread-safe.
 class View {
  public:

opencensus/stats/view_descriptor.h

@@ -26,37 +26,59 @@
 namespace opencensus {
 namespace stats {
 
-// ViewDescriptor provides metadata for a view, including its identity and the
-// data to be collected.
+// ViewDescriptor provides metadata for a view: a unique name, the measure to
+// collect data for, how to aggregate that data, and what tag keys to break it
+// down by.
+// In order to collect data for a ViewDescriptor, it must either be registered
+// for export (by calling RegisterForExport() on the fully-defined descriptor)
+// or converted into a View to collect data on-task (see view.h).
+//
 // ViewDescriptor is a value type, and is thread-compatible.
-// TODO: DOCS: Document members.
 class ViewDescriptor final {
  public:
   //////////////////////////////////////////////////////////////////////////////
   // View definition
 
+  // Creates a ViewDescriptor with Cumulative aggregation.
   ViewDescriptor();
 
+  // Sets the name of the ViewDescriptor. Names must be unique within the
+  // library; it is recommended that it be in the format "<domain>/<path>",
+  // where "<path>" uniquely specifies the measure, aggregation, and columns
+  // (e.g. "example.com/Foo/FooUsage-sum-key1-key2").
   ViewDescriptor& set_name(absl::string_view name);
   const std::string& name() const { return name_; }
 
   // Sets the measure. If no measure is registered under 'name' any View created
   // with the descriptor will be invalid.
   ViewDescriptor& set_measure(absl::string_view name);
-
+  // Accesses the descriptor of the view's measure. If no measure has been
+  // registered under the name set using set_measure(), this returns an invalid
+  // descriptor with blank fields.
   const MeasureDescriptor& measure_descriptor() const;
 
+  // Sets and retrieves the ViewDescriptor's aggregation. See aggregation.h for
+  // details of the options.
   ViewDescriptor& set_aggregation(const Aggregation& aggregation);
   const Aggregation& aggregation() const { return aggregation_; }
 
+  // Retrieves the AggregationWindow--see internal/aggregation_window.h for
+  // details. For exported views this should be left at the default Cumulative;
+  // for on-task data needing other windows, internal/set_aggregation_window.h
+  // provides an interface for setting this field.
   const AggregationWindow& aggregation_window() const {
     return aggregation_window_;
   }
 
+  // Adds a dimension to the view's data. When data is recorded it can specify a
+  // number of tags, key-value pairs; the aggregated data for each view will be
+  // broken down by the distinct values of each tag key matching one of the
+  // view's columns.
   ViewDescriptor& add_column(absl::string_view tag_key);
   size_t num_columns() const { return columns_.size(); }
   const std::vector<std::string>& columns() const { return columns_; }
 
+  // Sets a human-readable description for the view.
   ViewDescriptor& set_description(absl::string_view description);
   const std::string& description() const { return description_; }