chore: update API docs (#459)

* chore: update API docs * fix: review comment
open-telemetry · Oct 25, 2019 · 0392064 · 0392064
1 parent 91fd682
commit 0392064
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 9 deletions.
diff --git a/packages/opentelemetry-types/src/distributed_context/EntryValue.ts b/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;
 }
 

diff --git a/packages/opentelemetry-types/src/metrics/Handle.ts b/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;
 }

diff --git a/packages/opentelemetry-types/src/trace/SpanOptions.ts b/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;
 }
diff --git a/packages/opentelemetry-types/src/trace/link.ts b/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. */

diff --git a/packages/opentelemetry-types/src/trace/span_context.ts b/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 {
  /**

diff --git a/packages/opentelemetry-types/src/trace/tracer.ts b/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;
 }