docs: fix tsdoc comments to avoid warnings (#219)

* docs: fix tsdoc comments to avoid warnings

This commit contains changes to avoid all the tsdoc-related warnings
that occur during the build of the project.

* build: bump api-extractor/api-documenter to latest versions

Signed-off-by: Phil Adams <[email protected]>

Author: padamstx

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2022-04-04T16:42:23Z",
+  "generated_at": "2022-12-20T17:56:56Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -91,32 +91,32 @@
         "verified_result": null
       }
     ],
-    "MIGRATION-V1.md": [
+    "README.md": [
       {
-        "hashed_secret": "a00eada80f974d9446d54719567f67349cdc2d34",
+        "hashed_secret": "32e8612d8ca77c7ea8374aa7918db8e5df9252ed",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 19,
+        "line_number": 61,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "README.md": [
+    "auth/authenticators/authenticator.ts": [
       {
-        "hashed_secret": "32e8612d8ca77c7ea8374aa7918db8e5df9252ed",
+        "hashed_secret": "fdee05598fdd57ff8e9ae29e92c25a04f2c52fa6",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 61,
+        "line_number": 39,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "auth/authenticators/authenticator.ts": [
+    "auth/authenticators/basic-authenticator.ts": [
       {
-        "hashed_secret": "fdee05598fdd57ff8e9ae29e92c25a04f2c52fa6",
+        "hashed_secret": "bbccdf2efb33b52e6c9d0a14dd70b2d415fbea6e",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 39,
+        "line_number": 52,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -162,15 +162,15 @@
         "hashed_secret": "45c43fe97e3a06ab078b0eeff6fbe622cc417a25",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 91,
+        "line_number": 89,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "99833a8b234b57b886a9aef1dba187fdd7ceece8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 93,
+        "line_number": 91,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -224,23 +224,23 @@
         "hashed_secret": "f84f793e0af9ade37c8b927bc5091e98f35bf821",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 83,
+        "line_number": 84,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "45c43fe97e3a06ab078b0eeff6fbe622cc417a25",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 120,
+        "line_number": 118,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "99833a8b234b57b886a9aef1dba187fdd7ceece8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 122,
+        "line_number": 120,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -250,23 +250,23 @@
         "hashed_secret": "8f4bfc22c4fd7cb884f94ec175ff4a3284a174a1",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 58,
+        "line_number": 59,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "0358c67856fb6a21c4767daf02fcb8fe4dc0a318",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 61,
+        "line_number": 62,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "dbb19b8ae3b78f908e1467721fe4c9f0b0529d9b",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 62,
+        "line_number": 63,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -296,21 +296,11 @@
         "hashed_secret": "45c43fe97e3a06ab078b0eeff6fbe622cc417a25",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 273,
+        "line_number": 278,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "scripts/jsdoc/generate_index_html.sh": [
-      {
-        "hashed_secret": "973f71aa51bf4dcef6aa10f52089747a85c64a73",
-        "is_secret": false,
-        "is_verified": false,
-        "line_number": 19,
-        "type": "Base64 High Entropy String",
-        "verified_result": null
-      }
-    ],
     "test/resources/ibm-credentials.env": [
       {
         "hashed_secret": "5c5a15a8b0b3e154d77746945e563ba40100681b",
@@ -534,7 +524,7 @@
       }
     ]
   },
-  "version": "0.13.1+ibm.47.dss",
+  "version": "0.13.1+ibm.55.dss",
   "word_list": {
     "file": null,
     "hash": null

auth/authenticators/authenticator-interface.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,9 +40,8 @@ export interface AuthenticatorInterface {
   /**
    * Add authentication information to the specified request.
    *
-   * @param {object} requestOptions The request to augment with authentication information.
-   * @param {object.<string, string>} requestOptions.headers The headers the
-   *   authentication information will be added to.
+   * @param requestOptions - The request to which authentication information is added
+   * (in the headers field).
    */
   authenticate(requestOptions: AuthenticateOptions): Promise<void>;
 

auth/authenticators/authenticator.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unused-vars, class-methods-use-this */
 
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -45,8 +45,7 @@ export class Authenticator implements AuthenticatorInterface {
   /**
    * Create a new Authenticator instance.
    *
-   * @throws {Error} The `new` keyword was not used to create construct the
-   *   authenticator.
+   * @throws Error: the "new" keyword was not used to construct the authenticator.
    */
   constructor() {
     if (!(this instanceof Authenticator)) {
@@ -57,11 +56,8 @@ export class Authenticator implements AuthenticatorInterface {
   /**
    * Augment the request with authentication information.
    *
-   * @param {object} requestOptions - The request to augment with authentication information.
-   * @param {object.<string, string>} requestOptions.headers - The headers the
-   *   authentication information will be added too.
-   * @throws {Error} - The authenticate method was not implemented by a
-   *   subclass.
+   * @param requestOptions - The request to augment with authentication information.
+   * @throws Error: The authenticate method was not implemented by a subclass.
    */
   public authenticate(requestOptions: AuthenticateOptions): Promise<void> {
     const error = new Error('Should be implemented by subclass!');
@@ -72,7 +68,7 @@ export class Authenticator implements AuthenticatorInterface {
    * Retrieves the authenticator's type.
    * The returned value will be the same string that is used
    * when configuring an instance of the authenticator with the
-   * "<service_name>_AUTH_TYPE" configuration property
+   * \<service_name\>_AUTH_TYPE configuration property
    * (e.g. "basic", "iam", etc.).
    * This function should be overridden in each authenticator
    * implementation class that extends this class.

auth/authenticators/basic-authenticator.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,7 +33,7 @@ export type Options = {
  *
  * Basic Authorization will be sent as an Authorization header in the form:
  *
- *     Authorization: Basic <encoded username and password>
+ *     Authorization: Basic \<encoded username and password\>
  *
  */
 export class BasicAuthenticator extends Authenticator {
@@ -46,10 +46,12 @@ export class BasicAuthenticator extends Authenticator {
   /**
    * Create a new BasicAuthenticator instance.
    *
-   * @param {object} options Configuration options for basic authentication.
-   * @param {string} options.username The username portion of basic authentication.
-   * @param {string} options.password The password portion of basic authentication.
-   * @throws {Error} The configuration options are not valid.
+   * @param options - Configuration options for basic authentication.
+   * This should be an object containing these fields:
+   * - username: the username portion of basic authentication
+   * - password: the password portion of basic authentication
+   *
+   * @throws Error: the configuration options are not valid.
    */
   constructor(options: Options) {
     super();
@@ -60,14 +62,12 @@ export class BasicAuthenticator extends Authenticator {
   }
 
   /**
-   * Add basic authentication information to `request`. The basic authentication information
-   * will be set in the Authorization property of`request.headers` in the form:
+   * Add basic authentication information to `requestOptions`. The basic authentication information
+   * will be set in the Authorization property of `requestOptions.headers` in the form:
    *
-   *     Authorization: Basic <encoded username and password>
+   *     Authorization: Basic \<encoded username and password\>
    *
-   * @param {object} requestOptions - The request to augment with authentication information.
-   * @param {object.<string, string>} requestOptions.headers - The headers the
-   *   authentication information will be added too.
+   * @param requestOptions - The request to augment with authentication information.
    */
   public authenticate(requestOptions: AuthenticateOptions): Promise<void> {
     return new Promise((resolve) => {

auth/authenticators/bearer-token-authenticator.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,7 +31,7 @@ export type Options = {
  *
  * The bearer token will be sent as an Authorization header in the form:
  *
- *      Authorization: Bearer <bearer-token>
+ *      Authorization: Bearer \<bearer-token\>
  */
 export class BearerTokenAuthenticator extends Authenticator {
   protected requiredOptions = ['bearerToken'];
@@ -41,10 +41,10 @@ export class BearerTokenAuthenticator extends Authenticator {
   /**
    * Create a new BearerTokenAuthenticator instance.
    *
-   * @param {object} options Configuration options for bearer authentication.
-   * @param {string} options.bearerToken The bearer token to be added
-   *   to requests.
-   * @throws {Error} The configuration bearerToken is not valid, or unspecified.
+   * @param options - Configuration options for bearer authentication.
+   * This should be an object containing the "bearerToken" field.
+   *
+   * @throws Error: the options.bearerToken field is not valid, or unspecified
    */
   constructor(options: Options) {
     super();
@@ -57,23 +57,20 @@ export class BearerTokenAuthenticator extends Authenticator {
   /**
    * Set a new bearer token to be sent in subsequent requests.
    *
-   * @param {string} bearerToken The bearer token that will be sent in service
+   * @param bearerToken - The bearer token that will be sent in service
    *   requests.
    */
   public setBearerToken(bearerToken: string): void {
     this.bearerToken = bearerToken;
   }
 
   /**
-   * Add a bearer token to the `request`. The bearer token information
-   * will be set in the Authorization property of`request.headers` in the form:
+   * Add a bearer token to `requestOptions`. The bearer token information
+   * will be set in the Authorization property of "requestOptions.headers" in the form:
    *
-   *      Authorization: Bearer <bearer-token>
+   *      Authorization: Bearer \<bearer-token\>
    *
-   * @param {object} requestOptions - The request to augment with authentication
-   *   information.
-   * @param {object.<string, string>} requestOptions.headers - The headers the
-   *   authentication information will be added to.
+   * @param requestOptions - The request to augment with authentication information.
    */
   public authenticate(requestOptions: AuthenticateOptions): Promise<void> {
     return new Promise((resolve) => {

auth/authenticators/cloud-pak-for-data-authenticator.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,12 +31,12 @@ export interface Options extends BaseOptions {
 }
 
 /**
- * The [[CloudPakForDataAuthenticator]] will either use a username/password pair or a username/apikey pair to obtain
+ * The CloudPakForDataAuthenticator will either use a username/password pair or a username/apikey pair to obtain
  * a bearer token from a token server.  When the bearer token expires, a new token is obtained from the token server.
  *
  * The bearer token will be sent as an Authorization header in the form:
  *
- *      Authorization: Bearer <bearer-token>
+ *      Authorization: Bearer \<bearer-token\>
  */
 export class CloudPakForDataAuthenticator extends TokenRequestBasedAuthenticator {
   protected requiredOptions = ['username', 'url'];
@@ -50,19 +50,19 @@ export class CloudPakForDataAuthenticator extends TokenRequestBasedAuthenticator
   private apikey: string;
 
   /**
-   * Create a new [[CloudPakForDataAuthenticator]] instance.
+   * Create a new CloudPakForDataAuthenticator instance.
    *
-   * @param {object} options Configuration options for CloudPakForData authentication.
-   * @param {string} options.url For HTTP token requests.
-   * @param {string} options.username The username used to obtain a bearer token.
-   * @param {string} [options.password] The password used to obtain a bearer token [required if apikey not specified].
-   * @param {string} [options.apikey] The API key used to obtain a bearer token [required if password not specified].
-   * @param {boolean} [options.disableSslVerification] A flag that indicates
-   *   whether verification of the token server's SSL certificate should be
-   *   disabled or not
-   * @param {object<string, string>} [options.headers] to be sent with every.
-   * @throws `Error` The username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token
-   *   requests.
+   * @param options - Configuration options for CloudPakForData authentication.
+   * This should be an object containing these fields:
+   * - url: (required) the endpoint URL for the CloudPakForData token service
+   * - username: (required) the username used to obtain a bearer token
+   * - password: (optional) the password used to obtain a bearer token (required if apikey is not specified)
+   * - apikey: (optional) the API key used to obtain a bearer token (required if password is not specified)
+   * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+   * should be disabled or not
+   * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+   *
+   * @throws Error: the username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token requests.
    */
   constructor(options: Options) {
     super(options);