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

* chore: fix API docs

* update WEB Readme: WebTracer => WebTracerProvider

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.

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;

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;
 

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;
   }
 

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;