feat: Documenation

Author: HazAT

packages/browser/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "extends": "./tsconfig.build.json",
-  "include": ["src/**/*", "test/**/*", "../opentracing/src/sessiontracking.ts"],
+  "include": ["src/**/*", "test/**/*"],
   "exclude": ["dist"],
   "compilerOptions": {
     "rootDir": ".",

packages/opentracing/src/opentracingintegration.ts

@@ -19,27 +19,27 @@ export class OpenTracingIntegration implements Integration {
    * Constructor for OpenTracingIntegration
    *
    * @param traceId Optional TraceId that should be set into the integration.
-   * @param tracer Optional custom tracer that should be used.
+   * @param _tracer Optional custom tracer that should be used.
    */
-  public constructor(traceId?: string, private readonly tracer: Tracer = new Tracer()) {
-    tracer.setTraceId(traceId);
+  public constructor(traceId?: string, private readonly _tracer: Tracer = new Tracer()) {
+    _tracer.setTraceId(traceId);
   }
 
   /**
    * @inheritDoc
    */
   public setupOnce(): void {
-    const span = this.tracer.startSpan('sdk.init');
+    const span = this._tracer.startSpan('sdk.init');
     span.finish();
     setTimeout(() => {
-      this.tracer.flush();
+      this._tracer.flush();
     });
   }
 
   /**
    * Returns the Tracer which can be used as the parent.
    */
   public getTracer(): Tracer {
-    return this.tracer;
+    return this._tracer;
   }
 }

packages/opentracing/src/span.ts

@@ -3,18 +3,25 @@ import * as opentracing from 'opentracing';
 import { SpanContext } from './spancontext';
 import { Tracer } from './tracer';
 
-/** JSDoc */
+/**
+ * Interface for log entries.
+ */
 interface Log {
   data: { [key: string]: any };
   timestamp?: number;
 }
 
-/** JSDoc */
+/**
+ * Span represents a logical unit of work as part of a broader Trace. Examples
+ * of span might include remote procedure calls or a 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.
+ */
 export class Span extends opentracing.Span implements SpanInterface {
-  private flushed: boolean = false;
-  private finishTime: number = 0;
+  private _flushed: boolean = false;
+  private _finishTime: number = 0;
 
-  private readonly logs: Log[] = [];
+  private readonly _logs: Log[] = [];
 
   public tags: {
     [key: string]: string;
@@ -25,11 +32,11 @@ export class Span extends opentracing.Span implements SpanInterface {
   } = {};
 
   public constructor(
-    private readonly usedTracer: Tracer,
-    private operation: string,
-    private readonly spanContext: SpanContext,
-    private readonly references?: opentracing.Reference[],
-    private readonly startTime: number = Date.now(),
+    private readonly _usedTracer: Tracer,
+    private _operation: string,
+    private readonly _spanContext: SpanContext,
+    private readonly _references?: opentracing.Reference[],
+    private readonly _startTime: number = Date.now(),
   ) {
     super();
   }
@@ -38,29 +45,33 @@ export class Span extends opentracing.Span implements SpanInterface {
    * Returns the context.
    */
   protected _context(): SpanContext {
-    return this.spanContext;
+    return this._spanContext;
   }
 
   /**
    * Returns the tracer passed to the span.
    */
   protected _tracer(): Tracer {
-    return this.usedTracer;
+    return this._usedTracer;
   }
 
   /**
    * Sets the operation name.
    */
   protected _setOperationName(name: string): void {
-    this.operation = name;
+    this._operation = name;
   }
 
-  /** JSDoc */
+  /**
+   * Implementation for {@link setBaggageItem}
+   */
   protected _setBaggageItem(key: string, value: string): void {
     this.baggage[key] = value;
   }
 
-  /** JSDoc */
+  /**
+   * Implementation for {@link getBaggageItem}
+   */
   protected _getBaggageItem(key: string): string | undefined {
     return this.baggage[key];
   }
@@ -78,69 +89,69 @@ export class Span extends opentracing.Span implements SpanInterface {
   /**
    * Store log entry.
    */
-  protected _log(data: { [key: string]: any }, timestamp?: number): void {
-    this.logs.push({
+  protected _log(data: { [key: string]: any }, timestamp: number = Date.now() / 1000): void {
+    this._logs.push({
       data,
       timestamp,
     });
   }
 
   /**
-   * JSDoc
+   * Implementation for {@link finish}
    */
-  protected _finish(finishTime?: number): void {
-    this.finishTime = finishTime || Date.now();
+  protected _finish(finishTime: number = Date.now()): void {
+    this._finishTime = finishTime;
   }
 
   /**
    * Returns the operationName.
    */
   public getOperationName(): string {
-    return this.operation;
+    return this._operation;
   }
 
   /**
    * Returns the duration of the span.
    */
   public duration(): number {
-    return this.finishTime - this.startTime;
+    return this._finishTime - this._startTime;
   }
 
   /**
    * Returns wether the span has been finished.
    */
   public isFinished(): boolean {
-    return this.finishTime > 0;
+    return this._finishTime > 0;
   }
 
   /**
    * Marks the span as flushed.
    */
   public flush(): this {
-    this.flushed = true;
+    this._flushed = true;
     return this;
   }
 
   /**
    * Returns wether the span has already be flushed.
    */
   public isFlushed(): boolean {
-    return this.flushed;
+    return this._flushed;
   }
 
   /**
    * @inheritdoc
    */
   public toJSON(): object {
     return {
-      finish_time: (this.finishTime && this.finishTime / 1000) || undefined,
-      logs: this.logs.length === 0 ? undefined : this.logs,
-      operation: this.operation,
-      references: this.references && this.references,
-      span_id: this.spanContext.spanId,
-      start_time: this.startTime / 1000,
+      finish_time: (this._finishTime && this._finishTime / 1000) || undefined,
+      logs: this._logs.length === 0 ? undefined : this._logs,
+      operation: this._operation,
+      references: this._references && this._references,
+      span_id: this._spanContext.spanId,
+      start_time: this._startTime / 1000,
       tags: Object.keys(this.tags).length === 0 ? undefined : this.tags,
-      trace_id: this.spanContext.traceId,
+      trace_id: this._spanContext.traceId,
     };
   }
 }

packages/opentracing/src/spancontext.ts

@@ -1,6 +1,14 @@
 import { uuid4 } from '@sentry/utils/misc';
+
 /**
- * JSDoc
+ * SpanContext represents Span state that must propagate to descendant Spans
+ * and across process boundaries.
+ *
+ * SpanContext is logically divided into two pieces: the user-level "Baggage"
+ * (see setBaggageItem and getBaggageItem) that propagates across Span
+ * boundaries and any Tracer-implementation-specific fields that are needed to
+ * identify or otherwise contextualize the associated Span instance (e.g., a
+ * <trace_id, span_id, sampled> tuple).
  */
 export class SpanContext {
   public constructor(

packages/opentracing/src/tracer.ts

@@ -4,20 +4,28 @@ import { Span } from './span';
 import { SpanContext } from './spancontext';
 
 /**
- * JSDoc
+ * Tracer is the entry-point between the instrumentation API and the tracing
+ * implementation.
+ *
+ * The default object acts as a no-op implementation.
+ *
+ * Note to implementators: derived classes can choose to directly implement the
+ * methods in the "OpenTracing API methods" section, or optionally the subset of
+ * underscore-prefixed methods to pick up the argument checking and handling
+ * automatically from the base class.
  */
 export class Tracer extends opentracing.Tracer {
-  private traceId?: string = undefined;
-  private readonly spans: Span[] = [];
+  private _traceId?: string = undefined;
+  private readonly _spans: Span[] = [];
 
   /**
    * Called by public method startSpan
    * @param name Name of the operation
    * @param fields Options for the span {@link opentracing.SpanOptions}
    */
   protected _startSpan(name: string, fields: opentracing.SpanOptions): Span {
-    const span = new Span(this, name, new SpanContext(this.traceId), fields.references, fields.startTime);
-    this.spans.push(span);
+    const span = new Span(this, name, new SpanContext(this._traceId), fields.references, fields.startTime);
+    this._spans.push(span);
     return span;
   }
 
@@ -34,18 +42,18 @@ export class Tracer extends opentracing.Tracer {
    * @param traceId A string representing the traceId
    */
   public setTraceId(traceId?: string): void {
-    this.traceId = traceId;
+    this._traceId = traceId;
   }
 
   /**
    * Flushes all spans and sends an event
    */
   public flush(): void {
-    const finishedSpans = this.spans.filter((span: Span) => span.isFinished() && !span.isFlushed());
+    const finishedSpans = this._spans.filter((span: Span) => span.isFinished() && !span.isFlushed());
     if (finishedSpans.length) {
       getCurrentHub().captureEvent({
         spans: finishedSpans.map((span: Span) => span.flush()),
-        type: 'none',
+        type: 'none', // This ensures a Sentry event will not be created on the server
       });
     }
   }