doc: improve generated documentation (#410)

Adds some additional JSDoc properties so the docs are clearer.

Signed-off-by: Lance Ball <[email protected]>

Author: lance

src/message/http/index.ts

@@ -12,7 +12,14 @@ import {
 import { isStringOrObjectOrThrow, ValidationError } from "../../event/validation";
 import { JSONParser, MappedParser, Parser, parserByContentType } from "../../parsers";
 
-// implements Serializer
+/**
+ * Serialize a CloudEvent for HTTP transport in binary mode
+ * @implements {Serializer}
+ * @see https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md#31-binary-content-mode
+ *
+ * @param {CloudEvent} event The event to serialize
+ * @returns {Message} a Message object with headers and body
+ */
 export function binary(event: CloudEvent): Message {
   const contentType: Headers = { [CONSTANTS.HEADER_CONTENT_TYPE]: CONSTANTS.DEFAULT_CONTENT_TYPE };
   const headers: Headers = { ...contentType, ...headersFor(event) };
@@ -27,7 +34,14 @@ export function binary(event: CloudEvent): Message {
   };
 }
 
-// implements Serializer
+/**
+ * Serialize a CloudEvent for HTTP transport in structured mode
+ * @implements {Serializer}
+ * @see https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md#32-structured-content-mode
+ *
+ * @param {CloudEvent} event the CloudEvent to be serialized
+ * @returns {Message} a Message object with headers and body
+ */
 export function structured(event: CloudEvent): Message {
   if (event.data_base64) {
     // The event's data is binary - delete it
@@ -41,9 +55,15 @@ export function structured(event: CloudEvent): Message {
   };
 }
 
-// implements Detector
-// TODO: this could probably be optimized
+/**
+ * Determine if a Message is a CloudEvent
+ * @implements {Detector}
+ *
+ * @param {Message} message an incoming Message object
+ * @returns {boolean} true if this Message is a CloudEvent
+ */
 export function isEvent(message: Message): boolean {
+  // TODO: this could probably be optimized
   try {
     deserialize(message);
     return true;
@@ -54,6 +74,7 @@ export function isEvent(message: Message): boolean {
 
 /**
  * Converts a Message to a CloudEvent
+ * @implements {Deserializer}
  *
  * @param {Message} message the incoming message
  * @return {CloudEvent} A new {CloudEvent} instance

src/message/index.ts

@@ -6,6 +6,12 @@ import { binary, deserialize, structured, isEvent } from "./http";
  * Binding is an interface for transport protocols to implement,
  * which provides functions for sending CloudEvent Messages over
  * the wire.
+ * @interface
+ *
+ * @property {@link Serializer} `binary`     - converts a CloudEvent into a Message in binary mode
+ * @property {@link Serializer} `structured` - converts a CloudEvent into a Message in structured mode
+ * @property {@link Deserializer} `toEvent`  - converts a Message into a CloudEvent
+ * @property {@link Detector} `isEvent`      - determines if a Message can be converted to a CloudEvent
  */
 export interface Binding {
   binary: Serializer;
@@ -17,6 +23,7 @@ export interface Binding {
 /**
  * Headers is an interface representing transport-agnostic headers as
  * key/value string pairs
+ * @interface
  */
 export interface Headers extends IncomingHttpHeaders {
   [key: string]: string | string[] | undefined;
@@ -25,6 +32,9 @@ export interface Headers extends IncomingHttpHeaders {
 /**
  * Message is an interface representing a CloudEvent as a
  * transport-agnostic message
+ * @interface
+ * @property {@linkcode Headers} `headers` - the headers for the event Message
+ * @property string `body` - the body of the event Message
  */
 export interface Message {
   headers: Headers;
@@ -33,6 +43,7 @@ export interface Message {
 
 /**
  * An enum representing the two transport modes, binary and structured
+ * @interface
  */
 export enum Mode {
   BINARY = "binary",
@@ -42,6 +53,7 @@ export enum Mode {
 /**
  * Serializer is an interface for functions that can convert a
  * CloudEvent into a Message.
+ * @interface
  */
 export interface Serializer {
   (event: CloudEvent): Message;
@@ -50,6 +62,7 @@ export interface Serializer {
 /**
  * Deserializer is a function interface that converts a
  * Message to a CloudEvent
+ * @interface
  */
 export interface Deserializer {
   (message: Message): CloudEvent;
@@ -58,12 +71,16 @@ export interface Deserializer {
 /**
  * Detector is a function interface that detects whether
  * a message contains a valid CloudEvent
+ * @interface
  */
 export interface Detector {
   (message: Message): boolean;
 }
 
-// HTTP Message capabilities
+/**
+ * Bindings for HTTP transport support
+ * @implements {@linkcode Binding}
+ */
 export const HTTP: Binding = {
   binary: binary as Serializer,
   structured: structured as Serializer,

src/transport/emitter.ts

@@ -5,15 +5,17 @@ import { EventEmitter } from "events";
 /**
  * Options is an additional, optional dictionary of options that may
  * be passed to an EmitterFunction and TransportFunction
+ * @interface
  */
 export interface Options {
   [key: string]: string | Record<string, unknown> | unknown;
 }
 
 /**
- * EmitterFunction is an invokable interface returned by the emitterFactory
- * function. Invoke an EmitterFunction with a CloudEvent and optional transport
+ * EmitterFunction is an invokable interface returned by {@linkcode emitterFor}.
+ * Invoke an EmitterFunction with a CloudEvent and optional transport
  * options to send the event as a Message across supported transports.
+ * @interface
  */
 export interface EmitterFunction {
   (event: CloudEvent, options?: Options): Promise<unknown>;
@@ -23,18 +25,20 @@ export interface EmitterFunction {
  * TransportFunction is an invokable interface provided to the emitterFactory.
  * A TransportFunction's responsiblity is to send a JSON encoded event Message
  * across the wire.
+ * @interface
  */
 export interface TransportFunction {
   (message: Message, options?: Options): Promise<unknown>;
 }
 
 const emitterDefaults = { binding: HTTP, mode: Mode.BINARY };
 /**
- * emitterFactory creates and returns an EmitterFunction using the supplied
- * TransportFunction. The returned EmitterFunction will invoke the Binding's
- * `binary` or `structured` function to convert a CloudEvent into a JSON
- * Message based on the Mode provided, and invoke the TransportFunction with
- * the Message and any supplied options.
+ * Creates and returns an {@linkcode EmitterFunction} using the supplied
+ * {@linkcode TransportFunction}. The returned {@linkcode EmitterFunction}
+ * will invoke the {@linkcode Binding}'s `binary` or `structured` function
+ * to convert a {@linkcode CloudEvent} into a JSON
+ * {@linkcode Message} based on the {@linkcode Mode} provided, and invoke the
+ * TransportFunction with the Message and any supplied options.
  *
  * @param {TransportFunction} fn a TransportFunction that can accept an event Message
  * @param { {Binding, Mode} } options network binding and message serialization options
@@ -62,7 +66,7 @@ export function emitterFor(fn: TransportFunction, options = emitterDefaults): Em
 }
 
 /**
- * A static class to emit CloudEvents within an application
+ * A helper class to emit CloudEvents within an application
  */
 export class Emitter {
   /**
@@ -97,7 +101,7 @@ export class Emitter {
    * Emit an event inside this application
    *
    * @param {CloudEvent} event to emit
-   * @param {boolean} ensureDelivery fail the promise if one listener fail
+   * @param {boolean} ensureDelivery fail the promise if one listener fails
    * @return {void}
    */
   static async emitEvent(event: CloudEvent, ensureDelivery = true): Promise<void> {