chore: update some out-of-date comments and documentation (#176)

* comments: extract_or_create_span does not return an error
* comments: NullCollector is used in unit tests only
* documentation: src/ has been split into include/ and src/

include/datadog/null_collector.h

@@ -1,8 +1,7 @@
 #pragma once
 
 // This component provides a `class`, `NullCollector`, that implements the
-// `Collector` interface in terms of a no-op. It's used by `Tracer` in lieu
-// of a `DatadogAgent` whenever `TracerConfig::report_traces` is `false`.
+// `Collector` interface in terms of a no-op. It's used in unit tests.
 
 #include "collector.h"
 

include/datadog/tracer.h

@@ -71,10 +71,9 @@ class Tracer {
                               const SpanConfig& config);
 
   // Return a span extracted from the specified `reader` (see `extract_span`).
-  // If there is no span to extract, then return a span that is the root of a
-  // new trace (see `create_span`).  Optionally specify a `config` indicating
-  // the attributes of the span.  If a failure occurs, then return an error.
-  // Note that the absence of a span to extract is not considered an error.
+  // If there is no span to extract, or if an error occurs during extraction,
+  // then return a span that is the root of a new trace (see `create_span`).
+  // Optionally specify a `config` indicating the attributes of the span.
   Span extract_or_create_span(const DictReader& reader);
   Span extract_or_create_span(const DictReader& reader,
                               const SpanConfig& config);