docs: add jsdocs comments to the synthesize-stream class

Author: dpopp07

lib/recognize-stream.ts

@@ -54,7 +54,7 @@ interface RecognizeStream extends Duplex {
 }
 
 /**
- * pipe()-able Node.js Readable/Writeable stream - accepts binary audio and emits text in it's `data` events.
+ * pipe()-able Node.js Readable/Writeable stream - accepts binary audio and emits text in its `data` events.
  * Also emits `results` events with interim results and other data.
  *
  * Cannot be instantiated directly, instead created by calling #recognizeUsingWebSocket()

lib/synthesize-stream.ts

@@ -40,6 +40,15 @@ interface SynthesizeStream extends Readable {
   _readableState;
 }
 
+/**
+ * pipe()-able Node.js Readable stream - accepts text in the constructor and emits binary audio data in its 'message' events
+ *
+ * Cannot be instantiated directly, instead created by calling #synthesizeUsingWebSocket()
+ *
+ * Uses WebSockets under the hood.
+ * @param {Object} options
+ * @constructor
+ */
 class SynthesizeStream extends Readable {
 
   static WEBSOCKET_CONNECTION_ERROR: string = 'WebSocket connection error';
@@ -49,6 +58,31 @@ class SynthesizeStream extends Readable {
   private initialized: boolean;
   private authenticated: boolean;
 
+
+  /**
+   * pipe()-able Node.js Readable stream - accepts text and emits binary audio data in its 'message' events
+   *
+   * Uses WebSockets under the hood.
+   *
+   *
+   * Note that the WebSocket connection is not established until the first chunk of data is recieved. This allows for IAM token request management by the SDK.
+   *
+   * @param {Object} options
+   * @param {String} options.text - The text that us to be synthesized. Provide plain text or text that is annotated with SSML. SSML input can include the SSML <mark> element. Pass a maximum of 5 KB of text. 
+   * @param {String} options.accept - The requested audio format (MIME type) of the audio.
+   * @param {String[]} [options.timings] - An array that specifies whether the service is to return word timing information for all strings of the input text
+   * @param {String} [options.voice='en-US_MichaelVoice'] - The voice that is to be used for the synthesis.
+   * @param {String} [options.customization_id] - The customization ID (GUID) of a custom voice model that is to be used for the synthesis.
+   * @param {String} [options.url='wss://stream.watsonplatform.net/speech-to-text/api'] base URL for service
+   * @param {String} [options.watson-token] - Auth token
+   * @param {Object} [options.headers] - Only works in Node.js, not in browsers. Allows for custom headers to be set, including an Authorization header (preventing the need for auth tokens)
+   * @param {Boolean} [options.x-watson-learning-opt-out=false] - set to true to opt-out of allowing Watson to use this request to improve it's services
+   * @param {String} [options.x-watson-metadata] - Associates a customer ID with data that is passed over the connection.
+   * @param {IamTokenManagerV1} [options.token_manager] - Token manager for authenticating with IAM
+   * @param {Boolean} [options.rejectUnauthorized] - If true, disable SSL verification for the WebSocket connection
+   *
+   * @constructor
+   */
   constructor(options) {
     super(options);
     this.options = options;
@@ -144,6 +178,15 @@ class SynthesizeStream extends Readable {
     });
   }
 
+  /**
+   * This function retrieves an IAM access token and stores it in the
+   * request header before calling the callback function, which will
+   * execute the next iteration of `_read()`
+   *
+   *
+   * @private
+   * @param {Function} callback
+   */
    setAuthorizationHeaderToken(callback) {
     if (!this.authenticated) {
       this.options.token_manager.getToken((err, token) => {