Documentation updates. (#263)

* Add README for context/ and tags/ dirs.
* Add links to new materials on https://opencensus.io/.
* Improve span.h comments about thread safety and immutability.

Author: g-easy

opencensus/context/README.md

@@ -0,0 +1,7 @@
+# OpenCensus C++ Context library.
+
+Context is an object that holds information that is specific to an operation
+such as an RPC.
+
+Please refer to the [context documentation](../doc/context.md) for an
+explanation of how it's used.

opencensus/stats/README.md

@@ -1,10 +1,14 @@
 # Stats API
 
-The primary stats API documentation is in the headers in `opencensus/stats`.
+The primary stats API documentation is in the headers in this directory.
+
+There is also a stats [tutorial](https://opencensus.io/quickstart/cpp/metrics/)
+on the OpenCensus webpage.
+
 See the following classes and headers for the top-level interfaces:
 
 ### Recording data
-- A [`Measure`](measure.h) specifyies the resources against which data is
+- A [`Measure`](measure.h) specifies the resources against which data is
   recorded.
 - [`recording.h`](recording.h) defines the recording function.
 

opencensus/tags/README.md

@@ -0,0 +1,13 @@
+# OpenCensus C++ Tags library.
+
+This directory tree contains the C++ API and implementation of OpenCensus
+tagging.
+
+Please refer to the [tags documentation](https://opencensus.io/tag/) on the
+OpenCensus website.
+
+## API overview
+
+`TagMap` is an immutable map of `TagKey`s to tag values (strings).
+
+`TagKey` is a lightweight, immutable representation of a tag key (string).

opencensus/trace/README.md

@@ -3,10 +3,16 @@
 This directory tree contains the C++ API and implementation of OpenCensus
 tracing.
 
-The main entry point to tracing is the `span.h` file.
+The main entry point to tracing is the [`span.h`](span.h) file.
+It's a relatively short file and the comments are a reference guide
+to the tracing API.
 
 For a quick use guide, look at the `examples/` directory.
 
+Also see the tracing
+[tutorial](https://opencensus.io/quickstart/cpp/tracing/) on the OpenCensus
+website.
+
 ## Directory structure
 
 * `./` - headers that are the public API for tracing.
@@ -17,9 +23,12 @@ in-process storage.
 * `internal/` - internal implementation details and tests. Do not include or
 rely on headers from this directory!
 
+* `propagation/` - headers that are the public API for trace propagation, using
+different encodings.
+
 ## API overview
 
-`span.h` defines the central unit of tracing: Traces are made of Spans.
+`Span` is the central unit of tracing: Traces are made of Spans.
 
 `TraceId` is an opaque token that uniquely identifies a trace.
 
@@ -32,7 +41,7 @@ rely on headers from this directory!
 `TraceConfig` is a global that holds `TraceParams`.
 
 `TraceParams` configures the maximum number of Annotations, Attributes,
-              MessageEvents, and Links, as well as the sampler.
+MessageEvents, and Links, as well as the currently active `Sampler`.
 
 ---
 

opencensus/trace/span.h

@@ -69,12 +69,23 @@ struct StartSpanOptions {
   const std::vector<Span*> parent_links;
 };
 
-// Span represents a sub-operation in a larger Trace.
+// Span represents an operation. A Trace consists of one or more Spans.
 //
-// A Span is uniquely identified by a SpanContext. The Span object is just a
-// handle to add Annotations and Attributes in an implementation-defined data
-// structure, hence all these operations are marked const. The Span must be
-// explicitly End()ed when the suboperation is complete. Span is thread-safe.
+// A Span is uniquely identified by a SpanContext.
+//
+// A Span must be explicitly End()ed when the operation is complete.
+//
+// The Span object is just a handle to e.g. add Annotations in an
+// implementation-defined data structure, hence all operations on it are marked
+// const.
+//
+// Span is thread-compatible. If swap() and operator= are avoided, everything
+// else is thread-safe. Avoid mutating Span objects in-place; treat them like
+// read-only handles. When using multiple threads, give each thread a copy of
+// the Span.
+//
+// As an alternative to explicitly passing Span objects between functions,
+// consider using Context. (see the ../context/ directory).
 class Span final {
  public:
   // Constructs a no-op Span with an invalid context. Attempts to add
@@ -170,12 +181,13 @@ class Span final {
   friend void swap(Span& a, Span& b);
 
   // Spans that aren't sampled still have a valid SpanContext that propagates,
-  // but no span_impl_.
+  // but no span_impl_. The SpanContext should be treated as read-only but we
+  // can't mark it const because we need to swap() Spans.
   SpanContext context_;
 
   // Shared pointer to the underlying Span representation. This is nullptr for
   // Spans which are not recording events. This is an implementation detail, not
-  // part of the public API.
+  // part of the public API. We don't mark it const so that we can swap() Spans.
   std::shared_ptr<SpanImpl> span_impl_;
 
   friend class ::opencensus::context::Context;