Chore: minor fixes to API docs (open-telemetry#779)

* chore: fix API docs

* update WEB Readme: WebTracer => WebTracerProvider

doc/plugin-guide.md

@@ -1,6 +1,6 @@
 # Plugin Developer Guide
 
-The `NodeTracer` or `Node-SDK` is driven by a set of plugins that describe how to patch a module to generate trace spans when that module is used. We provide out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system (see [builtin plugins][builtin-plugins]), and provide a means for developers to create their own.
+The `NodeTracerProvider` or `Node-SDK` is driven by a set of plugins that describe how to patch a module to generate trace spans when that module is used. We provide out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system (see [builtin plugins][builtin-plugins]), and provide a means for developers to create their own.
 
 We strongly recommended to create a dedicated package for newly added plugin, example: `@opentelemetry/plugin-xxx`.
 

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

@@ -20,37 +20,29 @@ import { BoundCounter, BoundGauge, BoundMeasure } from './BoundInstrument';
 /**
  * An interface to allow the recording metrics.
  *
- * {@link Metric}s are used for recording pre-defined aggregation (Gauge and
- * Counter), or raw values ({@link Measure}) in which the aggregation and labels
+ * {@link Metric}s are used for recording pre-defined aggregation (`Gauge` and
+ * `Counter`), or raw values (`Measure`) in which the aggregation and labels
  * for the exported metric are deferred.
  */
 export interface Meter {
   /**
-   * Creates and returns a new {@link Measure}.
+   * Creates and returns a new `Measure`.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
   createMeasure(name: string, options?: MetricOptions): Metric<BoundMeasure>;
 
   /**
-   * Creates a new counter metric. Generally, this kind of metric when the
+   * Creates a new `counter` metric. Generally, this kind of metric when the
    * value is a quantity, the sum is of primary interest, and the event count
    * and value distribution are not of primary interest.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
   createCounter(name: string, options?: MetricOptions): Metric<BoundCounter>;
 
-  // TODO: Measurements can have a long or double type. However, it looks like
-  // the metric timeseries API (according to spec) accepts values instead of
-  // Measurements, meaning that if you accept a `number`, the type gets lost.
-  // Both java and csharp have gone down the route of having two gauge interfaces,
-  // GaugeDoubleTimeseries and GaugeLongTimeseries, with param for that type. It'd
-  // be cool to only have a single interface, but maybe having two is necessary?
-  // Maybe include the type as a metrics option? Probs a good gh issue, the same goes for Measure types.
-
   /**
-   * Creates a new gauge metric. Generally, this kind of metric should be used
+   * Creates a new `gauge` metric. Generally, this kind of metric should be used
    * when the metric cannot be expressed as a sum or because the measurement
    * interval is arbitrary. Use this kind of metric when the measurement is not
    * a quantity, and the sum and event count are not of interest.

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

@@ -21,8 +21,11 @@ import { Meter } from './Meter';
  */
 export interface MeterProvider {
   /**
-   * Returns a Meter, creating one if one with the given name and version is not already created
+   * Returns a Meter, creating one if one with the given name and version is
+   * not already created.
    *
+   * @param name The name of the meter or instrumentation library.
+   * @param version The version of the meter or instrumentation library.
    * @returns Meter A Meter with the given name and version
    */
   getMeter(name: string, version?: string): Meter;

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

@@ -81,7 +81,8 @@ export interface Metric<T> {
    * Returns a Instrument associated with specified LabelSet.
    * It is recommended to keep a reference to the Instrument instead of always
    * calling this method for every operations.
-   * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+   * @param labels the canonicalized LabelSet used to associate with this
+   *     metric instrument.
    */
   bind(labels: LabelSet): T;
 
@@ -92,7 +93,8 @@ export interface Metric<T> {
 
   /**
    * Removes the Instrument from the metric, if it is present.
-   * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+   * @param labels the canonicalized LabelSet used to associate with this
+   *     metric instrument.
    */
   unbind(labels: LabelSet): void;
 

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

@@ -21,8 +21,8 @@ import { DistributedContext } from '../distributed_context/DistributedContext';
 import { SpanContext } from '../trace/span_context';
 
 /**
- * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses constant
- * NoopMetrics for all of its methods.
+ * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses
+ * constant NoopMetrics for all of its methods.
  */
 export class NoopMeter implements Meter {
   constructor() {}
@@ -67,9 +67,10 @@ export class NoopMetric<T> implements Metric<T> {
   }
   /**
    * Returns a Bound Instrument associated with specified LabelSet.
-   * It is recommended to keep a reference to the Bound Instrument instead of always
-   * calling this method for every operations.
-   * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+   * It is recommended to keep a reference to the Bound Instrument instead of
+   * always calling this method for every operations.
+   * @param labels the canonicalized LabelSet used to associate with this
+   *     metric instrument.
    */
   bind(labels: LabelSet): T {
     return this._instrument;
@@ -84,10 +85,10 @@ export class NoopMetric<T> implements Metric<T> {
 
   /**
    * Removes the Binding from the metric, if it is present.
-   * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+   * @param labels the canonicalized LabelSet used to associate with this
+   *     metric instrument.
    */
   unbind(labels: LabelSet): void {
-    // @todo: implement this method
     return;
   }
 

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

@@ -21,10 +21,14 @@ import { Tracer } from './tracer';
  */
 export interface TracerProvider {
   /**
-   * Returns a Tracer, creating one if one with the given name and version is not already created
+   * 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.
+   * If there is no Span associated with the current context, `null` is
+   * returned.
    *
+   * @param name The name of the tracer or instrumentation library.
+   * @param version The version of the tracer or instrumentation library.
    * @returns Tracer A Tracer with the given name and version
    */
   getTracer(name: string, version?: string): Tracer;

packages/opentelemetry-metrics/src/Metric.ts

@@ -77,7 +77,8 @@ export abstract class Metric<T extends BaseBoundInstrument>
 
   /**
    * Removes the Instrument from the metric, if it is present.
-   * @param labelSet the canonicalized LabelSet used to associate with this metric instrument.
+   * @param labelSet the canonicalized LabelSet used to associate with this
+   *     metric instrument.
    */
   unbind(labelSet: types.LabelSet): void {
     this._instruments.delete(labelSet.identifier);

packages/opentelemetry-web/README.md

@@ -11,17 +11,17 @@ For manual instrumentation see the
 [@opentelemetry/tracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing) package.
 
 ## How does automatic tracing work?
-This package exposes a class `WebTracer` that will be able to automatically trace things in Browser only.
+This package exposes a class `WebTracerProvider` that will be able to automatically trace things in Browser only.
 
 See the example how to use it.
 
 OpenTelemetry comes with a growing number of instrumentation plugins for well know modules (see [supported modules](https://github.com/open-telemetry/opentelemetry-js#plugins)) and an API to create custom plugins (see [the plugin developer guide](https://github.com/open-telemetry/opentelemetry-js/blob/master/doc/plugin-guide.md)).
 
 Web Tracer currently supports one plugin for document load.
-Unlike Node Tracer, the plugins needs to be initialised and passed in configuration. 
-The reason is to give user full control over which plugin will be bundled into web page.   
+Unlike Node Tracer (`NodeTracerProvider`), the plugins needs to be initialised and passed in configuration.
+The reason is to give user full control over which plugin will be bundled into web page.
 
-You can choose to use the ZoneScopeManager if you want to trace asynchronous operations.
+You can choose to use the `ZoneScopeManager` if you want to trace asynchronous operations.
 
 ## Installation
 
@@ -33,27 +33,27 @@ npm install --save @opentelemetry/web
 
 ```js
 import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
-import { WebTracer } from '@opentelemetry/web';
+import { WebTracerProvider } from '@opentelemetry/web';
 import { DocumentLoad } from '@opentelemetry/plugin-document-load';
 import { ZoneScopeManager } from '@opentelemetry/scope-zone';
 
 // Minimum required setup - supports only synchronous operations
-const webTracer = new WebTracer({
+const provider = new WebTracerProvider({
   plugins: [
     new DocumentLoad()
   ]
 });
 
-webTracer.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
 
 // Changing default scopeManager to use ZoneScopeManager - supports asynchronous operations
-const webTracerWithZone = new WebTracer({
+const providerWithZone = new WebTracerProvider({
   scopeManager: new ZoneScopeManager(),
   plugins: [
     new DocumentLoad()
   ]
 });
-webTracerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
 
 ```
 

packages/opentelemetry-web/test/WebTracer.test.ts → packages/opentelemetry-web/test/WebTracerProvider.test.ts

@@ -33,7 +33,7 @@ class DummyPlugin extends BasePlugin<unknown> {
   unpatch() {}
 }
 
-describe('WebTracer', () => {
+describe('WebTracerProvider', () => {
   describe('constructor', () => {
     let defaultOptions: WebTracerConfig;