docs: add JSDocs for top level API objects

This commit add JSDoc documentation to the CloudEvent and HTTPReceiver
objects exposed by the API when using the top level imports, specifically
`CloudEvent` and `HTTPReceiver`.

Ref: #130

Signed-off-by: Lance Ball <lball@redhat.com>

Author: lance

.eslintrc

@@ -13,7 +13,7 @@
     "arrow-parens": ["error", "always"],
     "arrow-body-style": ["error", "as-needed"],
     "prefer-template": "error",
-    "max-len": ["warn", { "code": 80 }],
+    "max-len": ["warn", { "code": 120 }],
     "no-unused-vars": ["warn", {
       "argsIgnorePattern": "^_$|^e$|^reject$|^resolve$"
     }],

lib/bindings/http/http_receiver.js

@@ -4,7 +4,13 @@ const V1Binary = require("./receiver_binary_1.js");
 const V1Structured = require("./receiver_structured_1.js");
 const constants = require("./constants");
 
+/**
+ * A class to receive a CloudEvent from an HTTP POST request.
+ */
 class HTTPReceiver {
+  /**
+   * Create an instance of an HTTPReceiver to accept incoming CloudEvents.
+   */
   constructor() {
     this.receivers = {
       v1: {
@@ -18,6 +24,14 @@ class HTTPReceiver {
     };
   }
 
+  /**
+   * Acceptor for an incoming HTTP CloudEvent POST. Can process
+   * binary and structured incoming CloudEvents.
+   *
+   * @param {Object} headers HTTP headers keyed by header name ("Content-Type")
+   * @param {Object|JSON} body The body of the HTTP request
+   * @return {CloudEvent} A new {CloudEvent} instance
+   */
   accept(headers, body) {
     const mode = getMode(headers);
     const version = getVersion(mode, headers, body);

lib/cloudevent.js

@@ -1,24 +1,37 @@
 const Spec = require("./specs/spec_1.js");
 const Formatter = require("./formats/json/formatter.js");
 
-/*
- * Class created using the Builder Design Pattern.
- *
- * https://en.wikipedia.org/wiki/Builder_pattern
+/**
+ * An instance of a CloudEvent.
  */
 class CloudEvent {
-  constructor(_spec, _formatter) {
-    this.spec = (_spec) ? new _spec(CloudEvent) : new Spec(CloudEvent);
-    this.formatter = (_formatter) ? new _formatter() : new Formatter();
+  /**
+   * Creates a new CloudEvent instance
+   * @param {Spec} [UserSpec] A CloudEvent version specification
+   * @param {Formatter} [UserFormatter] Converts the event into a readable string
+   */
+  constructor(UserSpec, UserFormatter) {
+    this.spec = (UserSpec) ? new UserSpec(CloudEvent) : new Spec(CloudEvent);
+    this.formatter = (UserFormatter) ? new UserFormatter() : new Formatter();
 
     // The map of extensions
     this.extensions = {};
   }
 
+  /**
+   * Get the formatters available to this CloudEvent
+   * @returns {Object} a JSON formatter
+   */
   getFormats() {
     return { json: Formatter };
   }
 
+  /**
+   * Format the CloudEvent as JSON. Validates the event according
+   * to the CloudEvent specification and throws an exception if
+   * it's invalid.
+   * @returns {JSON} the CloudEvent in JSON form
+   */
   format() {
     // Check the constraints
     this.spec.check();
@@ -30,81 +43,174 @@ class CloudEvent {
     return this.formatter.format(this.spec.payload);
   }
 
+  /**
+   * Formats the CLoudEvent as JSON. No specification validation
+   * is performed.
+   * @returns {JSON} the CloudEvent in JSON form
+   */
   toString() {
     return this.formatter.toString(this.spec.payload);
   }
 
+  /**
+   * Sets the event type
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#type
+   * @param {string} type the type of event related to the originating source
+   * @returns {CloudEvent} this CloudEvent
+   */
   type(type) {
     this.spec.type(type);
     return this;
   }
 
+  /**
+   * Gets the event type
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#type
+   * @returns {String} the type of event related to the originating source
+   */
   getType() {
     return this.spec.getType();
   }
 
+  // TODO: The fact that this is exposed is problematic, given that it's
+  // immutable and this method will have no effect. The specification
+  // version is determined via the constructor - specifically the use
+  // of cloud event creator functions in /v03 and /v1. By default this
+  // object is created as a version 1.0 CloudEvent. Not documenting.
   specversion(version) {
     return this.spec.specversion(version);
   }
 
+  /**
+   * Gets the CloudEvent specification version
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#specversion
+   * @returns {string} The CloudEvent version that this event adheres to
+   */
   getSpecversion() {
     return this.spec.getSpecversion();
   }
 
-  source(_source) {
-    this.spec.source(_source);
+  /**
+   * Sets the origination source of this event.
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#source-1
+   * @param {URI} source the context in which the event happened
+   * @returns {CloudEvent} this CloudEvent instance
+   */
+  source(source) {
+    this.spec.source(source);
     return this;
   }
 
+  /**
+   * Gets the origination source of this event.
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#source-1
+   * @returns {string} the event source
+   */
   getSource() {
     return this.spec.getSource();
   }
 
-  id(_id) {
-    this.spec.id(_id);
+  /**
+   * Sets the event id. Source + id must be unique for each distinct event.
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#id
+   * @param {string} id source+id must be unique for each distinct event
+   * @returns {CloudEvent} this CloudEvent instance
+   */
+  id(id) {
+    this.spec.id(id);
     return this;
   }
 
+  /**
+   * Gets the event id.
+   * @returns {string} the event id
+   */
   getId() {
     return this.spec.getId();
   }
 
-  time(_time) {
-    this.spec.time(_time);
+  /**
+   * Sets the timestamp for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#time
+   * @param {Date} time timestamp when the event occurred
+   * @returns {CloudEvent} this CloudEvent instance
+   */
+  time(time) {
+    // TODO: Ensure that this is represented as a Date internally,
+    // or update the JSDoc
+    this.spec.time(time);
     return this;
   }
 
+  /**
+   * Gets the timestamp for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#time
+   * @returns {Date} the timestamp for this event
+   */
   getTime() {
+    // TODO: Ensure that this is represented as a Date internally,
+    // or update the JSDoc
     return this.spec.getTime();
   }
 
-  schemaurl(_schemaurl) {
-    this.spec.schemaurl(_schemaurl);
+  // TODO: Deprecated in 1.0
+  schemaurl(schemaurl) {
+    this.spec.schemaurl(schemaurl);
     return this;
   }
 
+  // TODO: Deprecated in 1.0
   getSchemaurl() {
     return this.spec.getSchemaurl();
   }
 
-  dataContenttype(_contenttype) {
-    this.spec.dataContenttype(_contenttype);
+  /**
+   * Sets the content type of the data value for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#datacontenttype
+   * @param {string} contenttype per https://tools.ietf.org/html/rfc2046
+   * @returns {CloudEvent} this CloudEvent instance
+   */
+  dataContenttype(contenttype) {
+    this.spec.dataContenttype(contenttype);
     return this;
   }
 
+  /**
+   * Gets the content type of the data value for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#datacontenttype
+   * @returns {string} the content type for the data in this event
+   */
   getDataContenttype() {
     return this.spec.getDataContenttype();
   }
 
-  data(_data) {
-    this.spec.data(_data);
+  /**
+   * Sets the data for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#event-data
+   * @param {*} data any data associated with this event
+   * @returns {CloudEvent} this CloudEvent instance
+   */
+  data(data) {
+    this.spec.data(data);
     return this;
   }
 
+  /**
+   * Gets any data that has been set for this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#event-data
+   * @returns {*} any data set for this event
+   */
   getData() {
     return this.spec.getData();
   }
 
+  /**
+   * Adds an extension attribute to this CloudEvent
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes
+   * @param {*} key the name of the exteneion attribute
+   * @param {*} value the value of the extension attribute
+   * @returns {CloudEvent} this CloudEvent instance
+   */
   addExtension(key, value) {
     this.spec.addExtension(key, value);
 
@@ -114,6 +220,12 @@ class CloudEvent {
     return this;
   }
 
+  /**
+   * Gets the extension attributes, if any, associated with this event
+   * @see https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes
+   * @returns {Object} the extensions attributes - if none exist will will be {}
+   * // TODO - this should return null or undefined if no extensions
+   */
   getExtensions() {
     return this.extensions;
   }