Update some docs (open-telemetry#1553)

lzchen · web-flow · commit ad894b19f531 · 2021-01-26T15:55:29.000-08:00
diff --git a/docs/examples/basic_tracer/basic_trace.py b/docs/examples/basic_tracer/basic_trace.py
@@ -1,3 +1,17 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import (
diff --git a/docs/examples/basic_tracer/resources.py b/docs/examples/basic_tracer/resources.py
@@ -1,3 +1,17 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 from opentelemetry import trace
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
diff --git a/opentelemetry-api/src/opentelemetry/baggage/propagation/__init__.py b/opentelemetry-api/src/opentelemetry/baggage/propagation/__init__.py
@@ -22,6 +22,9 @@
 
 
 class BaggagePropagator(textmap.TextMapPropagator):
+    """Extracts and injects Baggage which is used to annotate telemetry.
+    """
+
     MAX_HEADER_LENGTH = 8192
     MAX_PAIR_LENGTH = 4096
     MAX_PAIRS = 180
diff --git a/opentelemetry-api/src/opentelemetry/trace/__init__.py b/opentelemetry-api/src/opentelemetry/trace/__init__.py
@@ -338,6 +338,8 @@ def start_as_current_span(
                 be automatically set to ERROR when an uncaught exception is
                 raised in the span with block. The span status won't be set by
                 this mechanism if it was previously set manually.
+            end_on_exit: Whether to end the span automatically when leaving the
+                context manager.
 
         Yields:
             The newly-created span.
@@ -423,7 +425,7 @@ def get_tracer(
     This function is a convenience wrapper for
     opentelemetry.trace.TracerProvider.get_tracer.
 
-    If tracer_provider is ommited the current configured one is used.
+    If tracer_provider is omitted the current configured one is used.
     """
     if tracer_provider is None:
         tracer_provider = get_tracer_provider()
diff --git a/opentelemetry-api/src/opentelemetry/trace/propagation/textmap.py b/opentelemetry-api/src/opentelemetry/trace/propagation/textmap.py
@@ -25,16 +25,15 @@
 
 class Getter(typing.Generic[TextMapPropagatorT]):
     """This class implements a Getter that enables extracting propagated
-    fields from a carrier
-
+    fields from a carrier.
     """
 
     def get(
         self, carrier: TextMapPropagatorT, key: str
     ) -> typing.Optional[typing.List[str]]:
         """Function that can retrieve zero
         or more values from the carrier. In the case that
-        the value does not exist, returns an empty list.
+        the value does not exist, returns None.
 
         Args:
             carrier: An object which contains values that are used to
@@ -61,6 +60,14 @@ class DictGetter(Getter[typing.Dict[str, CarrierValT]]):
     def get(
         self, carrier: typing.Dict[str, CarrierValT], key: str
     ) -> typing.Optional[typing.List[str]]:
+        """Getter implementation to retrieve a value from a dictionary.
+
+        Args:
+            carrier: dictionary in which header
+            key: the key used to get the value
+        Returns:
+            A list with a single string with the value if it exists, else None.
+        """
         val = carrier.get(key, None)
         if val is None:
             return None
@@ -69,6 +76,7 @@ def get(
         return [val]
 
     def keys(self, carrier: typing.Dict[str, CarrierValT]) -> typing.List[str]:
+        """Keys implementation that returns all keys from a dictionary."""
         return list(carrier.keys())
 
 
diff --git a/opentelemetry-api/src/opentelemetry/trace/span.py b/opentelemetry-api/src/opentelemetry/trace/span.py
@@ -360,9 +360,9 @@ class SpanContext(
     Args:
         trace_id: The ID of the trace that this span belongs to.
         span_id: This span's ID.
+        is_remote: True if propagated from a remote parent.
         trace_flags: Trace options to propagate.
         trace_state: Tracing-system-specific info to propagate.
-        is_remote: True if propagated from a remote parent.
     """
 
     def __new__(
diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/resources/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/resources/__init__.py
@@ -32,15 +32,15 @@
 
 .. code-block:: python
 
-    metrics.set_meter_provider(
-        MeterProvider(
+    trace.set_tracer_provider(
+        TracerProvider(
             resource=Resource.create({
                 "service.name": "shoppingcart",
                 "service.instance.id": "instance-12",
             }),
         ),
     )
-    print(metrics.get_meter_provider().resource.attributes)
+    print(trace.get_tracer_provider().resource.attributes)
 
     {'telemetry.sdk.language': 'python',
     'telemetry.sdk.name': 'opentelemetry',
diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py
@@ -427,8 +427,8 @@ def __init__(
         sampler: Optional[sampling.Sampler] = None,
         trace_config: None = None,  # TODO
         resource: Resource = Resource.create({}),
-        attributes: types.Attributes = None,  # TODO
-        events: Sequence[Event] = None,  # TODO
+        attributes: types.Attributes = None,
+        events: Sequence[Event] = None,
         links: Sequence[trace_api.Link] = (),
         kind: trace_api.SpanKind = trace_api.SpanKind.INTERNAL,
         span_processor: SpanProcessor = SpanProcessor(),
@@ -899,6 +899,9 @@ def use_span(
 
 
 class TracerProvider(trace_api.TracerProvider):
+    """See `opentelemetry.trace.TracerProvider`.
+    """
+
     def __init__(
         self,
         sampler: sampling.Sampler = TRACE_SAMPLER,
diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py
@@ -38,8 +38,8 @@ class SpanExportResult(Enum):
 class SpanExporter:
     """Interface for exporting spans.
 
-    Interface to be implemented by services that want to export recorded in
-    its own format.
+    Interface to be implemented by services that want to export spans recorded
+    in their own format.
 
     To export data this MUST be registered to the :class`opentelemetry.sdk.trace.Tracer` using a
     `SimpleExportSpanProcessor` or a `BatchExportSpanProcessor`.
