chore: update API docs (#459)

* chore: update API docs

* fix: review comment

Author: mayurkale22

packages/opentelemetry-types/src/distributed_context/EntryValue.ts

@@ -19,7 +19,12 @@
  * DistributedContext}.
  */
 export interface EntryValue {
+  /** `String` value of the `EntryValue`. */
   value: string;
+  /**
+   * ttl is an integer that represents number of hops an entry can
+   * propagate.
+   */
   ttl?: EntryTtl;
 }
 

packages/opentelemetry-types/src/metrics/Handle.ts

@@ -21,7 +21,7 @@ import { SpanContext } from '../trace/span_context';
 export interface CounterHandle {
   /**
    * Adds the given value to the current value. Values cannot be negative.
-   * @param value the value to add
+   * @param value the value to add.
    */
   add(value: number): void;
 }

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

@@ -24,24 +24,30 @@ import { Link } from './link';
  * Options needed for span creation
  */
 export interface SpanOptions {
-  /** The SpanKind of a span */
+  /**
+   * The SpanKind of a span
+   * @default {@link SpanKind.INTERNAL}
+   */
   kind?: SpanKind;
 
   /** A spans attributes */
   attributes?: Attributes;
 
-  /** Indicates that if this Span is active and recording information like events with the `AddEvent` operation and attributes using `setAttributes`. */
+  /**
+   * Indicates that if this Span is active and recording information like
+   * events with the `AddEvent` operation and attributes using `setAttributes`.
+   */
   isRecording?: boolean;
 
   /** A spans links */
   links?: Link[];
 
   /**
-   * A parent SpanContext (or Span, for convenience) that the newly-started
+   * A parent `SpanContext` (or `Span`, for convenience) that the newly-started
    * span will be the child of.
    */
   parent?: Span | SpanContext;
 
-  /** A manually specified start time for the created Span object. */
+  /** A manually specified start time for the created `Span` object. */
   startTime?: number;
 }

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

@@ -19,7 +19,8 @@ import { SpanContext } from './span_context';
 
 /**
  * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace.
+ * in a different trace. Used (for example) in batching operations, where a
+ * single batch handler processes multiple requests from different traces.
  */
 export interface Link {
   /** The {@link SpanContext} of a linked span. */

packages/opentelemetry-types/src/trace/span_context.ts

@@ -19,7 +19,7 @@ import { TraceState } from './trace_state';
 
 /**
  * A SpanContext represents the portion of a {@link Span} which must be
- * serialized and propagated along side of a distributed context.
+ * serialized and propagated along side of a {@link DistributedContext}.
  */
 export interface SpanContext {
   /**

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

@@ -70,9 +70,11 @@ export interface Tracer {
    * Spans.
    *
    * If no tracer implementation is provided, this defaults to the W3C Trace
-   * Context binary format ({@link BinaryFormat}). For more details see
+   * Context binary format {@link BinaryFormat}. For more details see
    * <a href="https://w3c.github.io/trace-context-binary/">W3C Trace Context
    * binary protocol</a>.
+   *
+   * @returns the {@link BinaryFormat} for this implementation.
    */
   getBinaryFormat(): BinaryFormat;
 
@@ -81,8 +83,10 @@ export interface Tracer {
    * Spans.
    *
    * If no tracer implementation is provided, this defaults to the W3C Trace
-   * Context HTTP text format ({@link HttpTraceContext}). For more details see
+   * Context HTTP text format {@link HttpTextFormat}. For more details see
    * <a href="https://w3c.github.io/trace-context/">W3C Trace Context</a>.
+   *
+   * @returns the {@link HttpTextFormat} for this implementation.
    */
   getHttpTextFormat(): HttpTextFormat;
 }