Add TSDoc ESLint plugin

.eslintrc.json

@@ -1,6 +1,9 @@
 {
     "parser": "@typescript-eslint/parser",
-    "plugins": ["@typescript-eslint"],
+    "plugins": ["@typescript-eslint", "eslint-plugin-tsdoc"],
     "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
-    "root": true
+    "root": true,
+    "rules": {
+        "tsdoc/syntax": "error"
+    }
 }

package.json

@@ -67,6 +67,7 @@
         "chai": "^4.3.10",
         "chai-as-promised": "^7.1.1",
         "eslint": "^8.51.0",
+        "eslint-plugin-tsdoc": "^0.2.17",
         "mocha": "^10.2.0",
         "nyc": "^15.1.0",
         "shx": "^0.3.4",

src/authentication/credentials.ts

@@ -9,8 +9,10 @@ import { startInterval } from "../util/time";
 /**
  * A basic HTTP header.
  * @example
+ * ```ts
  *   { "Authorization": "Bearer xyz" }
  *   { "Content-Type": "application/json" }
+ * ```
  */
 export type HTTPHeader = StringMap<string>;
 

src/client/client.ts

@@ -25,8 +25,8 @@ export abstract class Client<
     /**
      * Construct a new client using the provided credentials.
      *
-     * @param apiBaseUrl the base URL for all HTTP requests
-     * @param credentials the credentials to use during authentication
+     * @param apiBaseUrl - the base URL for all HTTP requests
+     * @param credentials - the credentials to use during authentication
      */
     constructor(apiBaseUrl: string, credentials: T) {
         this.apiBaseURL = apiBaseUrl;
@@ -46,7 +46,7 @@ export abstract class Client<
      * Starts an informative timer which tells the user for how long they have
      * been waiting for a response already.
      *
-     * @param url the request URL
+     * @param url - the request URL
      * @returns the timer's handler
      */
     protected startResponseInterval(url: string): NodeJS.Timer {

src/client/jira/jiraClient.ts

@@ -34,8 +34,8 @@ export abstract class JiraClient<
     /**
      * Construct a new Jira client using the provided credentials.
      *
-     * @param apiBaseURL the Jira base endpoint
-     * @param credentials the credentials to use during authentication
+     * @param apiBaseURL - the Jira base endpoint
+     * @param credentials - the credentials to use during authentication
      */
     constructor(apiBaseURL: string, credentials: CredentialsType) {
         super(apiBaseURL, credentials);
@@ -44,11 +44,11 @@ export abstract class JiraClient<
     /**
      * Adds one or more attachments to an issue. Attachments are posted as multipart/form-data.
      *
-     * @param issueIdOrKey the ID or key of the issue that attachments are added to
-     * @param files the files to attach
+     * @param issueIdOrKey - issueIdOrKey the ID or key of the issue that attachments are added to
+     * @param files - files the files to attach
      * @returns a list of issue attachment responses or `undefined` in case of errors
      * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-attachments/#api-rest-api-3-issue-issueidorkey-attachments-post
-     * @see https://docs.atlassian.com/software/jira/docs/api/REST/9.7.0/#api/2/issue/{issueIdOrKey}/attachments-addAttachment
+     * @see https://docs.atlassian.com/software/jira/docs/api/REST/9.7.0/#api/2/issue/\{issueIdOrKey\}/attachments-addAttachment
      */
     public async addAttachment(
         issueIdOrKey: string,
@@ -115,7 +115,7 @@ export abstract class JiraClient<
     /**
      * Returns the endpoint to use for adding attchments to issues.
      *
-     * @param issueIdOrKey the ID or key of the issue that attachments are added to
+     * @param issueIdOrKey - the ID or key of the issue that attachments are added to
      * @returns the URL
      */
     public abstract getUrlAddAttachment(issueIdOrKey: string): string;
@@ -227,7 +227,7 @@ export abstract class JiraClient<
     /**
      * Searches for issues using JQL. Automatically performs pagination if necessary.
      *
-     * @param request the search request
+     * @param request - the search request
      * @returns the search results or `undefined` in case of errors
      * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-post
      * @see https://docs.atlassian.com/software/jira/docs/api/REST/9.9.1/#api/2/search-searchUsingSearchRequest
@@ -289,8 +289,8 @@ export abstract class JiraClient<
      * The parent field may be set by key or ID. For standard issue types, the parent may be removed
      * by setting `update.parent.set.none` to `true`.
      *
-     * @param issueIdOrKey the ID or key of the issue
-     * @param issueUpdateData the edit data
+     * @param issueIdOrKey - the ID or key of the issue
+     * @param issueUpdateData - the edit data
      * @returns the ID or key of the edited issue or `undefined` in case of errors
      * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-put
      * @see https://docs.atlassian.com/software/jira/docs/api/REST/9.10.0/#api/2/issue-editIssue
@@ -324,7 +324,7 @@ export abstract class JiraClient<
     /**
      * Returns the endpoint to use for editing issues.
      *
-     * @param issueIdOrKey the ID or key of the issue
+     * @param issueIdOrKey - the ID or key of the issue
      * @returns the endpoint
      */
     public abstract getUrlEditIssue(issueIdOrKey: string): string;

src/client/xray/xrayClient.ts

@@ -29,8 +29,8 @@ export abstract class XrayClient<
     /**
      * Construct a new client using the provided credentials.
      *
-     * @param apiBaseUrl the base URL for all HTTP requests
-     * @param credentials the credentials to use during authentication
+     * @param apiBaseUrl - the base URL for all HTTP requests
+     * @param credentials - the credentials to use during authentication
      */
     constructor(apiBaseUrl: string, credentials: CredentialsType) {
         super(apiBaseUrl, credentials);
@@ -39,7 +39,7 @@ export abstract class XrayClient<
     /**
      * Uploads test results to the Xray instance.
      *
-     * @param results the test results as provided by Cypress
+     * @param results - the test results as provided by Cypress
      * @returns the key of the test execution issue, `null` if the upload was skipped or `undefined`
      * in case of errors
      * @see https://docs.getxray.app/display/XRAYCLOUD/Import+Execution+Results+-+REST+v2
@@ -87,16 +87,16 @@ export abstract class XrayClient<
     /**
      * Returns the test execution key from the import execution response.
      *
-     * @param response the import execution response
+     * @param response - the import execution response
      * @returns the test execution issue key
      */
     public abstract handleResponseImportExecution(response: ImportExecutionResponseType): string;
 
     /**
      * Downloads feature (file) specifications from corresponding Xray issues.
      *
-     * @param keys a list of issue keys
-     * @param filter an integer that represents the filter ID
+     * @param keys - a list of issue keys
+     * @param filter - an integer that represents the filter ID
      * @returns the response of the Xray instance
      * @see https://docs.getxray.app/display/XRAYCLOUD/Exporting+Cucumber+Tests+-+REST+v2
      */
@@ -135,19 +135,19 @@ export abstract class XrayClient<
     /**
      * Returns the endpoint to use for exporting Cucumber feature files.
      *
-     * @param keys a list of issue keys
-     * @param filter an integer that represents the filter ID
+     * @param keys - a list of issue keys
+     * @param filter - an integer that represents the filter ID
      * @returns the URL
      */
     public abstract getUrlExportCucumber(issueKeys?: string[], filter?: number): string;
 
     /**
      * Uploads (zipped) feature file(s) to corresponding Xray issues.
      *
-     * @param file the (zipped) Cucumber feature file(s)
-     * @param projectKey key of the project where the tests and pre-conditions are going to be created
-     * @param projectId id of the project where the tests and pre-conditions are going to be created
-     * @param source a name designating the source of the features being imported (e.g. the source project name)
+     * @param file - the (zipped) Cucumber feature file(s)
+     * @param projectKey - key of the project where the tests and pre-conditions are going to be created
+     * @param projectId - id of the project where the tests and pre-conditions are going to be created
+     * @param source - a name designating the source of the features being imported (e.g. the source project name)
      * @returns `true` if the import was successful, `false` otherwise
      * @see https://docs.getxray.app/display/XRAY/Importing+Cucumber+Tests+-+REST
      * @see https://docs.getxray.app/display/XRAYCLOUD/Importing+Cucumber+Tests+-+REST+v2
@@ -192,9 +192,9 @@ export abstract class XrayClient<
     /**
      * Returns the endpoint to use for importing Cucumber feature files.
      *
-     * @param projectKey key of the project where the tests and pre-conditions are going to be created
-     * @param projectId id of the project where the tests and pre-conditions are going to be created
-     * @param source a name designating the source of the features being imported (e.g. the source project name)
+     * @param projectKey - key of the project where the tests and pre-conditions are going to be created
+     * @param projectId - id of the project where the tests and pre-conditions are going to be created
+     * @param source - a name designating the source of the features being imported (e.g. the source project name)
      * @returns the URL
      */
     public abstract getUrlImportFeature(
@@ -206,15 +206,15 @@ export abstract class XrayClient<
     /**
      * This method is called when a feature file was successfully imported to Xray.
      *
-     * @param response the import feature response
+     * @param response - the import feature response
      */
     public abstract handleResponseImportFeature(response: ImportFeatureResponseType): void;
 
     /**
      * Uploads Cucumber test results to the Xray instance.
      *
-     * @param cucumberJson the test results as provided by the `cypress-cucumber-preprocessor`
-     * @param cucumberInfo the test execution information
+     * @param cucumberJson - the test results as provided by the `cypress-cucumber-preprocessor`
+     * @param cucumberInfo - the test execution information
      * @returns the key of the test execution issue, `null` if the upload was skipped or `undefined`
      * in case of errors
      * @see https://docs.getxray.app/display/XRAY/Import+Execution+Results+-+REST#ImportExecutionResultsREST-CucumberJSONresultsMultipart
@@ -256,8 +256,8 @@ export abstract class XrayClient<
     /**
      * Prepares the Cucumber multipart import execution request.
      *
-     * @param cucumberJson the test results as provided by the `cypress-cucumber-preprocessor`
-     * @param cucumberInfo the test execution information
+     * @param cucumberJson - the test results as provided by the `cypress-cucumber-preprocessor`
+     * @param cucumberInfo - the test execution information
      * @returns the import execution request
      */
     public abstract prepareRequestImportExecutionCucumberMultipart(
@@ -268,7 +268,7 @@ export abstract class XrayClient<
     /**
      * Returns the test execution key from the Cucumber multipart import execution response.
      *
-     * @param response the import execution response
+     * @param response - the import execution response
      * @returns the test execution issue key
      */
     public abstract handleResponseImportExecutionCucumberMultipart(

src/client/xray/xrayClientCloud.ts

@@ -40,7 +40,7 @@ export class XrayClientCloud extends XrayClient<
     /**
      * Construct a new Xray cloud client using the provided credentials.
      *
-     * @param credentials the credentials to use during authentication
+     * @param credentials - the credentials to use during authentication
      */
     constructor(credentials: JWTCredentials) {
         super(XrayClientCloud.URL, credentials);
@@ -103,8 +103,8 @@ export class XrayClientCloud extends XrayClient<
      * Returns Xray test types for the provided test issues, such as `Manual`, `Cucumber` or
      * `Generic`.
      *
-     * @param projectKey key of the project containing the test issues
-     * @param issueKeys the keys of the test issues to retrieve test types for
+     * @param projectKey - key of the project containing the test issues
+     * @param issueKeys - the keys of the test issues to retrieve test types for
      * @returns a promise which will contain the mapping of issues to test types
      */
     public async getTestTypes(

src/client/xray/xrayClientServer.ts

@@ -26,9 +26,9 @@ export class XrayClientServer extends XrayClient<
     /**
      * Construct a new Xray Server client using the provided credentials.
      *
-     * @param apiBaseUrl the base URL for all HTTP requests
-     * @param credentials the credentials to use during authentication
-     * @param jiraClient the configured Jira client
+     * @param apiBaseUrl - the base URL for all HTTP requests
+     * @param credentials - the credentials to use during authentication
+     * @param jiraClient - the configured Jira client
      */
     constructor(
         apiBaseUrl: string,