Permalink
Browse files

Add support for ESDoc API documentation

  • Loading branch information...
1 parent f974c31 commit 9014587021b580b6edc2634534c0f977161e9d3b bcronin committed May 19, 2016
Showing with 53 additions and 58 deletions.
  1. +5 −0 esdoc.json
  2. +5 −3 src/singleton.js
  3. +12 −17 src/span.js
  4. +31 −38 src/tracer.js
View
@@ -0,0 +1,5 @@
+{
+ "source": "./src",
+ "destination": "./dist/apidoc",
+ "undocumentIdentifier": false
+}
View
@@ -5,7 +5,8 @@ import * as Constants from './constants';
import BinaryCarrier from './binary_carrier';
/**
- * The Singleton object extends the standard Tracer object so that the default
+ * The Singleton object is the default export of the package and extends the
+ * standard Tracer object so that the default
* exported object of the package can be conveniently be used both as the
* default tracer and an interface to the library.
*/
@@ -20,7 +21,7 @@ export default class Singleton extends Tracer {
*
* The behavior is undefined if this function is called more than once.
*
- * @param {TracerImp} The Tracer implementation object
+ * @param {TracerImp} tracerImp - the Tracer implementation object
*/
initGlobalTracer(tracerImp) {
this._imp = tracerImp;
@@ -49,7 +50,8 @@ export default class Singleton extends Tracer {
// Private and non-standard methods
// ---------------------------------------------------------------------- //
- /**
+ /* For internal use only:
+ *
* Creates the Singleton with no underlying implementation (i.e. defaults
* to no-op behavior for all functions).
*
View
@@ -181,20 +181,15 @@ export default class Span {
/**
* Explicitly create a log record associated with the span.
*
- * @param {[type]} fields [description]
- * @param {object} fields
- * Optional associative array of fields.
- * - `timestamp` {Number} Optional field specifying the timestamp
- * in milliseconds as a Unix timestamp. Fractional values are
- * allowed so that timestamps with sub-millisecond accuracy
- * can be represented. If not specified, the implementation
- * is expected to use it's notion of the current time of the
- * call.
- * - `event` {string}
- * The event name.
- * - `payload` {object}
- * An arbitrary structured payload. It is implementation-dependent
- * how this will be processed.
+ * @param {object} fields - object containing the log record properties
+ * @param {number} [fields.timestamp] - optional field specifying the
+ * timestamp in milliseconds as a Unix timestamp. Fractional values
+ * are allowed so that timestamps with sub-millisecond accuracy
+ * can be represented. If not specified, the implementation is
+ * expected to use it's notion of the current time of the call.
+ * @param {string} [fields.event] - the event name
+ * @param {object} [fields.payload] - an arbitrary structured payload. It is
+ * implementation-dependent how this will be processed.
*/
log(fields) {
if (API_CONFORMANCE_CHECKS) {
@@ -215,9 +210,9 @@ export default class Span {
/**
* Logs a event with an optional payload.
*
- * @param {string} eventName [description]
- * @param {} payload [description]
- * @return {[type]} [description]
+ * @param {string} eventName - string associated with the log record
+ * @param {object} [payload] - arbitrary payload object associated with the
+ * log record.
*/
logEvent(eventName, payload) {
return this.log({
View
@@ -18,28 +18,23 @@ export default class Tracer {
/**
* Starts and returns a new Span representing a logical unit of work.
*
- * @param {string|object} nameOrFields
- * If the given argument is a `string`, it is the name of the
- * the operation from the perpsective of the current service.
- *
- * If the given argument is a object, it is treated as a set of
- * fields to set on the newly created span.
- *
- * - `operationName` {string} Required. This is the name to use for
- * the newly created span.
- * - `parent` {Span} Optional. The newly created Span will be created
- * as a child of `parent`.
- * - `tags` {object} Optional set of key-value pairs which will be set as
- * tags on the newly created Span. Ownership of the object is
- * passed to the created span and the caller for efficiency
- * reasons.
- * - `startTime` {Number} Optional manually specified start time for the
- * created Span object. The time should be specified in
- * milliseconds as Unix timestamp. Decimal value are supported
- * to represent time values with sub-millisecond accuracy.
- *
- * @return {Span}
- * A new Span object.
+ * @param {string|object} nameOrFields - if the given argument is a
+ * string, it is the name of the operation and the second `fields`
+ * argument is optional. If it is an object, it is treated as the
+ * fields argument and a second argument should not be provided.
+ * @param {object} [fields] - the fields to set on the newly created span.
+ * @param {string} [fields.operationName] - the name to use for the newly
+ * created span. Required if called with a single argument.
+ * @param {Span} [fields.parent] - the parent of the newly created span
+ * @param {object} [fields.tags] - set of key-value pairs which will be set
+ * as tags on the newly created Span. Ownership of the object is
+ * passed to the created span for efficiency reasons (the caller
+ * should not modify this object after calling startSpan).
+ * @param {number} [fields.startTime] - a manually specified start time for
+ * the created Span object. The time should be specified in
+ * milliseconds as Unix timestamp. Decimal value are supported
+ * to represent time values with sub-millisecond accuracy.
+ * @return {Span} - a new Span object.
*/
startSpan(nameOrFields, fields) {
if (API_CONFORMANCE_CHECKS) {
@@ -108,12 +103,11 @@ export default class Tracer {
* binary data. Any valid Object can be used as long as the buffer field of
* the object can be set.
*
- * @param {Span} span
- * The span whose information should be injected into the carrier.
- * @param {string} format
- * The format of the carrier.
- * @param {any} carrier
- * See the method description for details on the carrier object.
+ * @param {Span} span - the span whose information should be injected into
+ * the carrier.
+ * @param {string} format - the format of the carrier.
+ * @param {any} carrier - see the method description for details on the
+ * carrier object.
*/
inject(span, format, carrier) {
if (API_CONFORMANCE_CHECKS) {
@@ -155,12 +149,11 @@ export default class Tracer {
* For FORMAT_BINARY, `carrier` is expected to have a field named `buffer`
* that contains an Array-like object (Array, ArrayBuffer, or TypedBuffer).
*
- * @param {string} operationName
- * Operation name to use on the newly created span.
- * @param {string} format
- * The format of the carrier.
- * @param {any} carrier
- * The type of the carrier object is determined by the format.
+ * @param {string} operationName - operation name to use on the newly
+ * created span.
+ * @param {string} format - the format of the carrier.
+ * @param {any} carrier - the type of the carrier object is determined by
+ * the format.
* @return {Span}
*/
join(operationName, format, carrier) {
@@ -193,10 +186,10 @@ export default class Tracer {
/**
* Request that any buffered or in-memory data is flushed out of the process.
*
- * @param {function} done
- * Optional callback function with the signature `function(err)` that
- * will be called as soon as the flush completes. `err` should be
- * null or undefined if the flush was successful.
+ * @param {function(err: objectg)} done - optional callback function with
+ * the signature `function(err)` that will be called as soon as the
+ * flush completes. `err` should be null or undefined if the flush
+ * was successful.
*/
flush(done) {
if (API_CONFORMANCE_CHECKS) {

0 comments on commit 9014587

Please sign in to comment.