refactor: add jsdoc to core package

Author: eduardoemery

packages/opencensus-core/src/exporters/buffer.ts

@@ -24,11 +24,11 @@ import {Exporter} from './types';
 import {Config, BufferConfig} from '../trace/config/types';
 
 
-/**
- * Controls the sending of traces to exporters
- */
+/** Controls the sending of traces to exporters. */
 export class Buffer {
+  /** The service to send the collected spans. */
   private exporter: Exporter;
+  /** Maximum size of a buffer. */
   private bufferSize: number;
   /** Trace queue of a buffer */
   private queue: RootSpan[] = [];
@@ -39,6 +39,11 @@ export class Buffer {
   /** Indicates when the buffer timeout is running */
   private bufferTimeoutInProgress = false;
 
+  /**
+   * Constructs a new Buffer instance.
+   * @param exporter The service to send the collected spans.
+   * @param config A buffer configuration object to create a buffer.
+   */
   constructor(exporter: Exporter, config: BufferConfig) {
     this.exporter = exporter;
     this.bufferSize = config.bufferSize;
@@ -47,17 +52,17 @@ export class Buffer {
   }
 
   /**
-   * Set the buffer size value
-   * @param bufferSize The new buffer size
+   * Set the buffer size value.
+   * @param bufferSize The new buffer size.
    */
   setBufferSize(bufferSize: number) {
     this.bufferSize = bufferSize;
     return this;
   }
 
   /**
-   * Add a trace (rootSpan) in the buffer
-   * @param trace RootSpan to be added in the buffer
+   * Add a trace (rootSpan) in the buffer.
+   * @param trace RootSpan to be added in the buffer.
    */
   addToBuffer(trace: RootSpan) {
     this.queue.push(trace);

packages/opencensus-core/src/exporters/console-exporter.ts

@@ -19,7 +19,6 @@ import {RootSpan} from '../trace/model/types';
 import {Buffer} from './buffer';
 
 
-
 /** Do not send span data */
 export class NoopExporter implements Exporter {
   onEndSpan(root: RootSpan) {}
@@ -28,12 +27,22 @@ export class NoopExporter implements Exporter {
 
 /** Format and sends span data to the console. */
 export class ConsoleLogExporter implements Exporter {
+  /** Buffer object to store the spans. */
   private buffer: Buffer;
 
+  /**
+   * Constructs a new ConsoleLogExporter instance.
+   * @param config Exporter configuration object to create a console log
+   * exporter.
+   */
   constructor(config: ExporterConfig) {
     this.buffer = new Buffer(this, config);
   }
 
+  /**
+   * Event called when a span is ended.
+   * @param root Ended span.
+   */
   onEndSpan(root: RootSpan) {
     this.buffer.addToBuffer(root);
   }

packages/opencensus-core/src/exporters/types.ts

@@ -16,9 +16,15 @@
 
 
 import {OnEndSpanEventListener, RootSpan} from '../trace/model/types';
-import { BufferConfig } from '../trace/config/types';
+import {BufferConfig} from '../trace/config/types';
 
+/** Defines an exporter interface. */
 export interface Exporter extends OnEndSpanEventListener {
+  
+  /**
+   * Sends a list of root spans to the service.
+   * @param rootSpans A list of root spans to publish.
+   */
   publish(rootSpans: RootSpan[]);
 }
 

packages/opencensus-core/src/internal/clock.ts

@@ -14,19 +14,24 @@
  * limitations under the License.
  */
 
+/** Defines a Clock. */
 export class Clock {
-  private endedLocal: boolean;
+  /** Indicates if the clock is endend. */
+  private endedLocal = false;
+  /** Indicates the clock's start time. */
   private startTimeLocal: Date;
+  /** The time in high resolution in a [seconds, nanoseconds]. */
   private hrtimeLocal: [number, number];
-  private diff: [number, number];
+  /** The duration between start and end of the clock. */
+  private diff: [number, number] = null;
 
+  /** Constructs a new SamplerImpl instance. */
   constructor() {
-    this.endedLocal = false;
     this.startTimeLocal = new Date();
     this.hrtimeLocal = process.hrtime();
-    this.diff = null;
   }
 
+  /** Ends the clock. */
   end(): void {
     if (this.endedLocal) {
       return;
@@ -35,6 +40,7 @@ export class Clock {
     this.endedLocal = true;
   }
 
+  /** Gets the duration of the clock. */
   get duration(): number {
     if (!this.endedLocal) {
       return null;
@@ -43,21 +49,31 @@ export class Clock {
     return ns / 1e6;
   }
 
+  /**
+   * Compares clock with another one.
+   * @param timer A clock object to compare.
+   */
   offset(timer: Clock): number {
     const a = timer.hrtime;
     const b = this.hrtime;
     const ns = (b[0] - a[0]) * 1e9 + (b[1] - a[1]);
     return ns / 1e6;
   }
 
+  /** Gets the time in high definition. */
   get hrtime(): [number, number] {
     return this.hrtimeLocal;
   }
 
+  /** Starts the clock. */
   get startTime(): Date {
     return this.startTimeLocal;
   }
 
+  /**
+   * Gets the time so far.
+   * @returns A Date object with the current duration.
+   */
   get endTime(): Date {
     let result: Date = null;
     if (this.ended) {
@@ -66,6 +82,7 @@ export class Clock {
     return result;
   }
 
+  /** Indicates if the clock was ended. */
   get ended(): boolean {
     return this.endedLocal;
   }

packages/opencensus-core/src/trace/config/types.ts

@@ -1,45 +1,39 @@
 import {Exporter} from '../../exporters/types';
 import {PluginNames} from '../instrumentation/types';
 
-/**
- * This interface represent the probability of a tracer.
- */
+/** This interface represent the probability of a tracer. */
 export interface Sampler {
-
   /**
-   * Set idUpperBound with MAX_NUMBER that is equivalent the probability be 1
-   * @returns a Sampler object
+   * Sets idUpperBound with MAX_NUMBER that is equivalent the probability be 1.
+   * @returns a Sampler object.
    */
-
   always(): Sampler;
+
   /**
-   * Set idUpperBound with MIN_NUMBER that is equivalent the probability be 0
-   * @returns a Sampler object
+   * Sets idUpperBound with MIN_NUMBER that is equivalent the probability be 0.
+   * @returns a Sampler object.
    */
-
   never(): Sampler;
 
   /**
-   * Set idUpperBound with the probability. If probability
+   * Sets idUpperBound with the probability. If probability
    * parameter is bigger then 1 set always. If probability parameter less
    * than 0, set never.
-   * @param probability probability between 0 and 1
-   * @returns a Sampler object
+   * @param probability probability between 0 and 1.
+   * @returns a Sampler object.
    */
   probability(probability: number): Sampler;
 
   /**
    * Checks if trace belong the sample.
-   * @param traceId Used to check the probability
+   * @param traceId Used to check the probability.
    * @returns a boolean. True if the traceId is in probability
    * False if the traceId is not in probability.
    */
   shouldSample(traceId: string): boolean;
 }
 
-/**
- * Interface configuration for a buffer 
- */
+/** Interface configuration for a buffer. */
 export interface BufferConfig {
   bufferSize?: number;
   bufferTimeout?: number;

packages/opencensus-core/src/trace/instrumentation/base-plugin.ts

@@ -16,21 +16,28 @@
 import * as shimmer from 'shimmer';
 import {Tracer} from '../model/types';
 
-/**
- * This class represent the base to patch plugin
- */
+/** This class represent the base to patch plugin. */
 export abstract class BasePlugin {
+  /** The service to send the collected traces */
   // tslint:disable:no-any
   exporter: any;
+  /** The module name */
   moduleName: string;
+  /** A tracer object. */
   tracer: Tracer;
+  /** The module version. */
   version: string;
 
+  /**
+   * Constructs a new BasePlugin instance.
+   * @param moduleName The module name.
+   */
   constructor(moduleName: string) {
     this.moduleName = moduleName;
   }
+
   /**
-   * Set modified plugin to the context.
+   * Sets modified plugin to the context.
    * @param exporter object module to set on context
    * @param tracer tracer relating to context
    * @param version module version description
@@ -42,21 +49,42 @@ export abstract class BasePlugin {
     this.version = version;
   }
 
+  /**
+   * Wraps a function.
+   * @param nodule The module.
+   * @param name The function name.
+   * @param wrapper The wrapper.
+   */
   protected wrap(nodule, name, wrapper) {
       shimmer.wrap(nodule, name, wrapper);
   }
 
+  /**
+   * Unwraps a function.
+   * @param nodule The module.
+   * @param name The function name.
+   */
   protected unwrap(nodule, name) {
       shimmer.unwrap(nodule, name);
   }
 
+  /**
+   * Wraps one or more funcitons.
+   * @param nodule The module.
+   * @param names A list of function names.
+   * @param wrapper The wrapper.
+   */
   protected massWrap(nodule,names, wrapper) {
      shimmer.massWrap(nodule, names, wrapper);
   } 
 
+  /**
+   * Unwraps one or more functions.
+   * @param nodule The module.
+   * @param names The list of function names.
+   */
   protected massUnwrap(nodule,names) {
     shimmer.massUnwrap(nodule, names);
   } 
 
- 
 }

packages/opencensus-core/src/trace/instrumentation/types.ts

@@ -16,9 +16,7 @@
 
 import {Tracer} from "../model/types";
 
-/**
- * Interface Plugin to apply patch.
- */
+/** Interface Plugin to apply patch. */
 export interface Plugin {
   // tslint:disable:no-any
   applyPatch(module: {}, tracer: Tracer, version: string): any;

packages/opencensus-core/src/trace/model/root-span.ts

@@ -26,11 +26,18 @@ import {OnEndSpanEventListener, RootSpan, Span, TraceContext, TraceOptions, Trac
 
 /** Defines a root span */
 export class RootSpanImpl extends SpanBaseModel implements RootSpan {
+  /** A tracer object */
   private tracer: Tracer;
+  /** A list of child spans. */
   private spansLocal: Span[];
+  /** It's trace ID. */
   private traceIdLocal: string;
 
-  // TODO - improve root name setup
+  /**
+   * Constructs a new RootSpanImpl instance.
+   * @param tracer A tracer object.
+   * @param context A trace options object to build the root span.
+   */
   constructor(tracer: Tracer, context?: TraceOptions) {
     super();
     this.tracer = tracer;
@@ -45,25 +52,25 @@ export class RootSpanImpl extends SpanBaseModel implements RootSpan {
     this.spansLocal = [];
   }
 
-  /** Get span list from rootspan instance */
+  /** Gets span list from rootspan instance. */
   get spans(): Span[] {
     return this.spansLocal;
   }
 
-  /** Get trace id from rootspan instance */
+  /** Gets trace id from rootspan instance. */
   get traceId(): string {
     return this.traceIdLocal;
   }
 
-  /** Start a rootspan instance */
+  /** Starts a rootspan instance. */
   start() {
     super.start();
     debug(
         'starting %s  %o', this.className,
         {traceId: this.traceId, id: this.id, parentSpanId: this.parentSpanId});
   }
 
-  /** End a rootspan instance */
+  /** Ends a rootspan instance. */
   end() {
     super.end();
 
@@ -78,8 +85,8 @@ export class RootSpanImpl extends SpanBaseModel implements RootSpan {
   }
 
   /**
-   * Event called when a span ended
-   * @param span Span ended
+   * Event called when a span is ended.
+   * @param span Span ended.
    */
   onEndSpan(span: Span) {
     debug('ending span  %o', {
@@ -93,10 +100,10 @@ export class RootSpanImpl extends SpanBaseModel implements RootSpan {
   }
 
   /**
-   * Start a new span linked with the rootspan
-   * @param name Span name
-   * @param type Span type
-   * @param parentSpanId Span parent ID
+   * Starts a new child span in the root span.
+   * @param name Span name.
+   * @param type Span type.
+   * @param parentSpanId Span parent ID.
    */
   startSpan(name: string, type: string, parentSpanId?: string) {
     if (this.ended) {