chore: improve API documentation (open-telemetry#1106)

* chore: improve API documentation

* chore: add @link

* fix: code review

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>

packages/opentelemetry-api/README.md

@@ -9,13 +9,14 @@ This package provides everything needed to interact with the OpenTelemetry API,
 
 ## Quick Start
 
-To get started tracing you need to install the SDK and plugins, create a TracerProvider, and register it with the API.
+To get started you need to install the SDK and plugins, create a TracerProvider and/or MeterProvider, and register it with the API.
 
 ### Install Dependencies
 
 ```sh
 $ # Install tracing dependencies
 $ npm install \
+    @opentelemetry/api \
     @opentelemetry/core \
     @opentelemetry/node \
     @opentelemetry/tracing \
@@ -28,6 +29,8 @@ $ npm install \
     @opentelemetry/exporter-prometheus # add exporters as needed
 ```
 
+> Note: this example is for node.js. See [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/tracer-web) for a browser example.
+
 ### Initialize the SDK
 
 Before any other module in your application is loaded, you must initialize the global tracer and meter providers. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.
@@ -50,9 +53,9 @@ const tracerProvider = new NodeTracerProvider();
  */
 tracerProvider.addSpanProcessor(
   new SimpleSpanProcessor(
-    new JaegerExporter(
-      /* export options */
-    )
+    new JaegerExporter({
+      serviceName: 'my-service'
+    })
   )
 );
 
@@ -124,18 +127,18 @@ If you are writing an instrumentation library, or prefer to call the API methods
 ```javascript
 const api = require("@opentelemetry/api");
 
-/* Initialize TraceProvider */
-api.trace.setGlobalTracerProvider(traceProvider);
-/* returns traceProvider (no-op if a working provider has not been initialized) */
+/* Initialize TracerProvider */
+api.trace.setGlobalTracerProvider(tracerProvider);
+/* returns tracerProvider (no-op if a working provider has not been initialized) */
 api.trace.getTracerProvider();
-/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized); */
+/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized) */
 api.trace.getTracer(name, version);
 
 /* Initialize MeterProvider */
 api.metrics.setGlobalMeterProvider(meterProvider);
 /* returns meterProvider (no-op if a working provider has not been initialized) */
 api.metrics.getMeterProvider();
-/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized); */
+/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized) */
 api.metrics.getMeter(name, version);
 
 /* Initialize Propagator */
@@ -172,7 +175,6 @@ async function doSomething() {
 }
 ```
 
-
 ## Useful links
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>

packages/opentelemetry-api/src/context/propagation/HttpTextPropagator.ts

@@ -19,20 +19,22 @@ import { SetterFunction } from './setter';
 import { GetterFunction } from './getter';
 
 /**
- * Injects {@link Context} into and extracts it from carriers that travel
+ * Injects `Context` into and extracts it from carriers that travel
  * in-band across process boundaries. Encoding is expected to conform to the
  * HTTP Header Field semantics. Values are often encoded as RPC/HTTP request
  * headers.
  *
  * The carrier of propagated data on both the client (injector) and server
- * (extractor) side is usually an object such as http headers.
+ * (extractor) side is usually an object such as http headers. Propagation is
+ * usually implemented via library-specific request interceptors, where the
+ * client-side injects values and the server-side extracts them.
  */
 export interface HttpTextPropagator {
   /**
-   * Injects values from a given {@link Context} into a carrier.
+   * Injects values from a given `Context` into a carrier.
    *
-   * OpenTelemetry defines a common set of format values (HttpTextPropagator), and
-   * each has an expected `carrier` type.
+   * OpenTelemetry defines a common set of format values (HttpTextPropagator),
+   * and each has an expected `carrier` type.
    *
    * @param context the Context from which to extract values to transmit over
    *     the wire.
@@ -44,7 +46,7 @@ export interface HttpTextPropagator {
   inject(context: Context, carrier: unknown, setter: SetterFunction): void;
 
   /**
-   * Given a {@link Context} and a carrier, extract context values from a
+   * Given a `Context` and a carrier, extract context values from a
    * carrier and return a new context, created from the old context, with the
    * extracted values.
    *

packages/opentelemetry-api/src/metrics/MeterProvider.ts

@@ -17,7 +17,7 @@
 import { Meter } from './Meter';
 
 /**
- * MeterProvider provides an interface for creating {@link Meter}s
+ * A registry for creating named {@link Meter}s.
  */
 export interface MeterProvider {
   /**

packages/opentelemetry-api/src/metrics/Metric.ts

@@ -106,6 +106,21 @@ export interface UnboundMetric<T> extends Metric {
   unbind(labels: Labels): void;
 }
 
+/**
+ * Counter is the most common synchronous instrument. This instrument supports
+ * an `Add(increment)` function for reporting a sum, and is restricted to
+ * non-negative increments. The default aggregation is Sum, as for any additive
+ * instrument.
+ *
+ * Example uses for Counter:
+ * <ol>
+ *   <li> count the number of bytes received. </li>
+ *   <li> count the number of requests completed. </li>
+ *   <li> count the number of accounts created. </li>
+ *   <li> count the number of checkpoints run. </li>
+ *   <li> count the number of 5xx errors. </li>
+ * <ol>
+ */
 export interface Counter extends UnboundMetric<BoundCounter> {
   /**
    * Adds the given value to the current value. Values cannot be negative.

packages/opentelemetry-api/src/trace/NoopTracerProvider.ts

@@ -19,8 +19,10 @@ import { Tracer } from './tracer';
 import { TracerProvider } from './tracer_provider';
 
 /**
- * An implementation of the {@link TracerProvider} which returns an impotent Tracer
- * for all calls to `getTracer`
+ * An implementation of the {@link TracerProvider} which returns an impotent
+ * Tracer for all calls to `getTracer`.
+ *
+ * All operations are no-op.
  */
 export class NoopTracerProvider implements TracerProvider {
   getTracer(_name?: string, _version?: string): Tracer {

packages/opentelemetry-api/src/trace/SpanOptions.ts

@@ -30,10 +30,10 @@ export interface SpanOptions {
    */
   kind?: SpanKind;
 
-  /** A spans attributes */
+  /** A span's attributes */
   attributes?: Attributes;
 
-  /** A spans links */
+  /** {@link Link}s span to other spans */
   links?: Link[];
 
   /**

packages/opentelemetry-api/src/trace/attributes.ts

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 
-/** Defines a attributes interface. */
+/**
+ * Defines a attributes interface.
+ * These attributes provides additional data about the {@link Span}.
+ */
 export interface Attributes {
   [attributeKey: string]: unknown;
 }

packages/opentelemetry-api/src/trace/link.ts

@@ -19,8 +19,18 @@ import { LinkContext } from './link_context';
 
 /**
  * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace. Used (for example) in batching operations, where a
- * single batch handler processes multiple requests from different traces.
+ * in a different trace.
+ * Few examples of Link usage.
+ * 1. Batch Processing: A batch of elements may contain elements associated
+ *    with one or more traces/spans. Since there can only be one parent
+ *    SpanContext, Link is used to keep reference to SpanContext of all
+ *    elements in the batch.
+ * 2. Public Endpoint: A SpanContext in incoming client request on a public
+ *    endpoint is untrusted from service provider perspective. In such case it
+ *    is advisable to start a new trace with appropriate sampling decision.
+ *    However, it is desirable to associate incoming SpanContext to new trace
+ *    initiated on service provider side so two traces (from Client and from
+ *    Service Provider) can be correlated.
  */
 export interface Link {
   /** The {@link LinkContext} of a linked span. */

packages/opentelemetry-api/src/trace/span.ts

@@ -25,18 +25,26 @@ import { TimeInput } from '../common/Time';
  * in-process function calls to sub-components. A Trace has a single, top-level
  * "root" Span that in turn may have zero or more child Spans, which in turn
  * may have children.
+ *
+ * Spans are created by the {@link Tracer.startSpan} method.
  */
 export interface Span {
   /**
    * Returns the {@link SpanContext} object associated with this Span.
    *
+   * Get an immutable, serializable identifier for this span that can be used
+   * to create new child spans. Returned SpanContext is usable even after the
+   * span ends.
+   *
    * @returns the SpanContext object associated with this Span.
    */
   context(): SpanContext;
 
   /**
    * Sets an attribute to the span.
    *
+   * Sets a single Attribute with the key and value passed as arguments.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    */
@@ -66,7 +74,8 @@ export interface Span {
 
   /**
    * Sets a status to the span. If used, this will override the default Span
-   * status. Default is {@link CanonicalCode.OK}.
+   * status. Default is {@link CanonicalCode.OK}. SetStatus overrides the value
+   * of previous calls to SetStatus on the Span.
    *
    * @param status the Status to set.
    */
@@ -75,6 +84,11 @@ export interface Span {
   /**
    * Updates the Span name.
    *
+   * This will override the name provided via {@link Tracer.startSpan}.
+   *
+   * Upon this update, any sampling behavior based on Span name will depend on
+   * the implementation.
+   *
    * @param name the Span name.
    */
   updateName(name: string): this;
@@ -97,7 +111,7 @@ export interface Span {
    * Returns the flag whether this span will be recorded.
    *
    * @returns true if this Span is active and recording information like events
-   * with the AddEvent operation and attributes using setAttributes.
+   *     with the `AddEvent` operation and attributes using `setAttributes`.
    */
   isRecording(): boolean;
 }

packages/opentelemetry-api/src/trace/tracer.ts

@@ -29,28 +29,48 @@ export interface Tracer {
   /**
    * Returns the current Span from the current context if available.
    *
-   * If there is no Span associated with the current context, null is returned.
+   * If there is no Span associated with the current context, `null` is
+   * returned.
+   *
+   * To install a {@link Span} to the current Context use
+   * {@link Tracer.withSpan}.
    *
    * @returns Span The currently active Span
    */
   getCurrentSpan(): Span | undefined;
 
   /**
-   * Starts a new {@link Span}.
+   * Starts a new {@link Span}. Start the span without setting it as the current
+   * span in this tracer's context.
+   *
+   * This method do NOT modify the current Context. To install a {@link
+   * Span} to the current Context use {@link Tracer.withSpan}.
+   *
    * @param name The name of the span
    * @param [options] SpanOptions used for span creation
    * @param [context] Context to use to extract parent
    * @returns Span The newly created span
+   * @example
+   *     const span = tracer.startSpan('op');
+   *     span.setAttribute('key', 'value');
+   *     span.end();
    */
   startSpan(name: string, options?: SpanOptions, context?: Context): Span;
 
   /**
-   * Executes the function given by fn within the context provided by Span
+   * Executes the function given by fn within the context provided by Span.
+   *
+   * This is a convenience method for creating spans attached to the tracer's
+   * context. Applications that need more control over the span lifetime should
+   * use {@link Tracer.startSpan} instead.
    *
    * @param span The span that provides the context
    * @param fn The function to be executed inside the provided context
    * @example
-   * tracer.withSpan(span, function() { ... });
+   *     tracer.withSpan(span, () => {
+   *         tracer.getCurrentSpan().addEvent("parent's event");
+   *         doSomeOtherWork();  // Here "span" is the current Span.
+   *     });
    */
   withSpan<T extends (...args: unknown[]) => ReturnType<T>>(
     span: Span,

packages/opentelemetry-api/src/trace/tracer_provider.ts

@@ -17,15 +17,15 @@
 import { Tracer } from './tracer';
 
 /**
- * TracerProvider provides an interface for creating {@link Tracer}s
+ * A registry for creating named {@link Tracer}s.
  */
 export interface TracerProvider {
   /**
    * Returns a Tracer, creating one if one with the given name and version is
    * not already created.
    *
-   * If there is no Span associated with the current context, `null` is
-   * returned.
+   * This function may return different Tracer types (e.g.
+   * {@link NoopTracerProvider} vs. a functional tracer).
    *
    * @param name The name of the tracer or instrumentation library.
    * @param version The version of the tracer or instrumentation library.