Add typedoc docs (#56)

* Add typedoc docs

* oops, yarn run docs -> yarn docs

* Fix review comments

- Rename docs to documentation
- Add lerna run docs

* set out to docs/out

* Change out path

.gitignore

@@ -66,3 +66,6 @@ yarn.lock
 package-lock.json
 packages/**/yarn.lock
 packages/**/package-lock.json
+
+# docs files
+docs

CONTRIBUTING.md

@@ -51,3 +51,4 @@ The `opentelemetry-js` project is written in TypeScript.
 - `yarn bootstrap` or `npm run bootstrap` Bootstrap the packages in the current Lerna repo. Installs all of their dependencies and links any cross-dependencies.
 - `yarn test` or `npm test` tests code the same way that our CI will test it.
 - `yarn fix` or `npm run fix` lint (and maybe fix) any changes.
+- `yarn docs` or `npm run docs` to generate API documentation.

package.json

@@ -12,7 +12,8 @@
     "bootstrap": "lerna bootstrap",
     "bump": "lerna publish",
     "codecov": "lerna run codecov",
-    "check": "lerna run check"
+    "check": "lerna run check",
+    "docs": "lerna run docs"
   },
   "repository": "open-telemetry/opentelemetry-js",
   "keywords": [

packages/opentelemetry-types/package.json

@@ -10,7 +10,8 @@
     "check": "gts check",
     "compile": "tsc -p .",
     "fix": "gts fix",
-    "test": "npm run compile && npm run check"
+    "test": "npm run compile && npm run check",
+    "docs": "typedoc --tsconfig tsconfig.json"
   },
   "keywords": [
     "opentelemetry",
@@ -38,6 +39,7 @@
   },
   "devDependencies": {
     "gts": "^1.0.0",
+    "typedoc": "^0.14.2",
     "typescript": "^3.4.5"
   }
 }

packages/opentelemetry-types/src/trace/link.ts

@@ -18,12 +18,12 @@ import { Attributes } from './attributes';
 import { SpanContext } from './span_context';
 
 /**
- * A pointer from the current span to another span in the same trace or in a
- * different trace.
+ * A pointer from the current {@link Span} to another span in the same trace or
+ * in a different trace.
  */
 export interface Link {
-  /** The SpanContext of a linked span. */
+  /** The {@link SpanContext} of a linked span. */
   spanContext: SpanContext;
-  /** A set of attributes on the link. */
+  /** A set of {@link Attributes} on the link. */
   attributes?: Attributes;
 }

packages/opentelemetry-types/src/trace/span.ts

@@ -27,7 +27,7 @@ import { Attributes } from './attributes';
  */
 export interface Span {
   /**
-   * Returns the SpanContext object associated with this Span.
+   * Returns the {@link SpanContext} object associated with this Span.
    *
    * @returns the SpanContext object associated with this Span.
    */
@@ -62,7 +62,7 @@ export interface Span {
    * @param [attributes] the attributes that will be added; these are
    *     associated with this event.
    */
-  addEvent(name: string, attributes?: { [key: string]: unknown }): this;
+  addEvent(name: string, attributes?: Attributes): this;
 
   /**
    * Adds a link to the Span.
@@ -71,14 +71,11 @@ export interface Span {
    * @param [attributes] the attributes that will be added; these are
    *     associated with this link.
    */
-  addLink(
-    spanContext: SpanContext,
-    attributes?: { [key: string]: unknown }
-  ): this;
+  addLink(spanContext: SpanContext, attributes?: Attributes): this;
 
   /**
    * Sets a status to the span. If used, this will override the default Span
-   * status. Default is 'OK'.
+   * status. Default is {@link CanonicalCode.OK}.
    *
    * @param status the Status to set.
    */

packages/opentelemetry-types/src/trace/span_context.ts

@@ -18,8 +18,8 @@ import { TraceState } from './trace_state';
 import { TraceOptions } from './trace_options';
 
 /**
- * A SpanContext represents the portion of a Span which must be serialized and
- * propagated along side of a distributed context.
+ * A SpanContext represents the portion of a {@link Span} which must be
+ * serialized and propagated along side of a distributed context.
  */
 export interface SpanContext {
   /**

packages/opentelemetry-types/tsconfig.json

@@ -6,5 +6,11 @@
   },
   "include": [
     "src/**/*.ts"
-  ]
+  ],
+  "typedocOptions": {
+    "name": "OpenTelemetry Documentation",
+    "out": "docs/out",
+    "mode": "file",
+    "hideGenerator": true
+  }
 }