docs: added TypeDoc annotations

Signed-off-by: Ilona Shishov <[email protected]>

src/caNotification.ts

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * Interface representing the data structure for a Component Analysis (CA) Notification.
+ */
 interface CANotificationData {
   errorMessage: string;
   done: boolean;
@@ -8,6 +11,9 @@ interface CANotificationData {
   vulnCount: Map<string, number>;
 }
 
+/**
+ * Provides functionality for generating a Component Analysis (CA) Notification.
+ */
 class CANotification {
   private readonly errorMessage: string;
   private readonly done: boolean;
@@ -24,6 +30,10 @@ class CANotification {
   private static readonly SHIELD = 'shield';
   private static readonly CHECK = 'check';
 
+  /**
+   * Creates an instance of CANotification based on the given data.
+   * @param respData The data used to create the notification.
+   */
   constructor(respData: CANotificationData) {
     this.errorMessage = respData.errorMessage || '';
     this.done = respData.done === true;
@@ -33,53 +43,109 @@ class CANotification {
     this.totalVulnCount = Object.values(this.vulnCount).reduce((sum, cv) => sum + cv, 0);
   }
 
+  /**
+   * Determines if a singular or plural form of a word should be used based on the number of vulnerabilities.
+   * @param num The number of vulnerabilities to evaluate.
+   * @returns The appropriate string representing either 'vulnerability' or 'vulnerabilities'.
+   * @private
+   */
   private singularOrPlural(num: number): string {
     return num === 1 ? CANotification.VULNERABILITY : CANotification.VULNERABILITIES;
   }
 
+  /**
+   * Capitalizes each word in a given string.
+   * @param inputString The string to be capitalized.
+   * @returns The string with each word capitalized.
+   * @private
+   */
   private capitalizeEachWord(inputString: string): string {
     return inputString.replace(/\b\w/g, (match) => match.toUpperCase());
   }
 
+  /**
+   * Generates text for the total vulnerability count.
+   * @returns Text representing the total number of vulnerabilities.
+   * @private
+   */
   private vulnCountText(): string {
     return this.totalVulnCount > 0 ? `${this.totalVulnCount} direct ${this.singularOrPlural(this.totalVulnCount)}` : `no ${CANotification.VULNERABILITIES}`;
   }
 
+  /**
+   * Generates the text for the in-progress status.
+   * @returns Text representing the in-progress status.
+   * @private
+   */
   private inProgressText(): string {
-    return `$(${CANotification.SYNC_SPIN}) Dependency analysis in progress`;
+    return `$(${CANotification.SYNC_SPIN}) RHDA analysis in progress`;
   }
 
+  /**
+   * Generates the text for the warning status for amount of vulnerabilities found.
+   * @returns Text representing the amount of vulnerabilities found.
+   * @private
+   */
   private warningText(): string {
     return `$(${CANotification.WARNING}) ${this.vulnCountText()} found for all the providers combined`;
   }
 
+  /**
+   * Generates the default text for the status.
+   * @returns Default text for the status.
+   * @private
+   */
   private defaultText(): string {
     return `$(${CANotification.SHIELD})$(${CANotification.CHECK})`;
   }
 
+  /**
+   * Retrieves the error message associated with the notification.
+   * @returns The error message, if available; otherwise, an empty string.
+   */
   public errorMsg(): string {
     return this.errorMessage;
   }
 
+  /**
+   * Retrieves the URI associated with the notification.
+   * @returns The URI string.
+   */
   public origin(): string {
     return this.uri;
   }
 
+  /**
+   * Checks if the analysis is done.
+   * @returns A boolean value indicating if the analysis is done or not.
+   */
   public isDone(): boolean {
     return this.done;
   }
 
+  /**
+   * Checks if any diagnostic have been found in the analysis.
+   * @returns A boolean indicating if diagnostics have been found.
+   */
   public hasWarning(): boolean {
     return this.diagCount > 0;
   }
 
+  /**
+   * Generates the text to display in the notification popup.
+   * @returns The text content for the popup notification.
+   */
   public popupText(): string {
     const text: string = Object.entries(this.vulnCount)
       .map(([provider, vulnCount]) => `Found ${vulnCount} direct ${this.singularOrPlural(vulnCount)} for ${this.capitalizeEachWord(provider)} Provider.`)
       .join(' ');
     return text || this.warningText().replace(/\$\((.*?)\)/g, '');
   }
 
+  /**
+   * Generates the text to display in the status bar.
+   * @returns The text content for the status bar.
+   */
   public statusText(): string {
     if (!this.isDone()) {
       return this.inProgressText();

src/caStatusBarProvider.ts

@@ -5,13 +5,24 @@ import { Disposable } from 'vscode-languageclient';
 import { PromptText } from './constants';
 import * as commands from './commands';
 
+/**
+ * Provides status bar functionality for the extension.
+ */
 class CAStatusBarProvider implements Disposable {
     private statusBarItem: StatusBarItem;
 
+    /**
+     * Creates an instance of the CAStatusBarProvider class.
+     */
     constructor() {
         this.statusBarItem = window.createStatusBarItem(StatusBarAlignment.Left, 0);
     }
 
+    /**
+     * Displays summary information in the status bar.
+     * @param text The text to display in the status bar.
+     * @param uri The URI associated with the summary.
+     */
     public showSummary(text: string, uri: string): void {
         this.statusBarItem.text = text;
         this.statusBarItem.command = {
@@ -23,17 +34,26 @@ class CAStatusBarProvider implements Disposable {
         this.statusBarItem.show();
     }
 
+    /**
+     * Sets an error message in the status bar indicating a failed RHDA analysis.
+     */
     public setError(): void {
-        this.statusBarItem.text = `$(error) Dependency analysis has failed`;
+        this.statusBarItem.text = `$(error) RHDA analysis has failed`;
         this.statusBarItem.command = {
             title: PromptText.LSP_FAILURE_TEXT,
             command: commands.TRIGGER_STACK_LOGS,
         };
     }
 
+    /**
+     * Disposes of the status bar item.
+     */
     public dispose(): void {
         this.statusBarItem.dispose();
     }
 }
 
+/**
+ * Provides an instance of CAStatusBarProvider for use across the extension.
+ */
 export const caStatusBarProvider: CAStatusBarProvider = new CAStatusBarProvider();

src/config.ts

@@ -6,6 +6,9 @@ import { GlobalState } from './constants';
 import * as commands from './commands';
 import { getTelemetryId } from './redhatTelemetry';
 
+/**
+ * Represents the configuration settings for the extension.
+ */
 class Config {
   telemetryId: string;
   triggerFullStackAnalysis: string;
@@ -32,26 +35,41 @@ class Config {
   private readonly DEFAULT_PIP_EXECUTABLE = 'pip';
 
   /**
-   * Initializes a new instance of the EnvironmentData class with default extension workspace settings.
+   * Creates an instance of the Config class.
+   * Initializes the instance with default extension workspace settings.
    */
   constructor() {
     this.loadData();
     this.setProcessEnv();
   }
 
-  private getApiConfig(): any {
+  /**
+   * Retrieves RHDA configuration settings from the workspace.
+   * @returns The RHDA configuration settings.
+   * @private
+   */
+  private getRhdaConfig(): any {
     return vscode.workspace.getConfiguration('redHatDependencyAnalytics');
   }
 
+  /**
+   * Retrieves the path for an executable from the workspace.
+   * @param exe The name of the executable.
+   * @returns The path of the executable if specified in the workspace configuration, otherwise the default value.
+   * @private
+   */
   private getExecutableConfig(exe: string): string {
     const exePath: string = vscode.workspace
       .getConfiguration(`${exe}.executable`)
       .get<string>('path');
     return exePath ? exePath : exe;
   }
 
+  /**
+   * Loads configuration settings from the workspace.
+   */
   loadData() {
-    const apiConfig = this.getApiConfig();
+    const apiConfig = this.getRhdaConfig();
 
     this.triggerFullStackAnalysis = commands.TRIGGER_FULL_STACK_ANALYSIS;
     this.utmSource = GlobalState.UTM_SOURCE;
@@ -69,6 +87,10 @@ class Config {
     this.exhortPipPath = this.getExecutableConfig(this.DEFAULT_PIP_EXECUTABLE);
   }
 
+  /**
+   * Sets process environment variables based on configuration settings.
+   * @private
+   */
   private setProcessEnv() {
     process.env['VSCEXT_TRIGGER_FULL_STACK_ANALYSIS'] = this.triggerFullStackAnalysis;
     process.env['VSCEXT_UTM_SOURCE'] = this.utmSource;
@@ -86,12 +108,19 @@ class Config {
     process.env['EXHORT_DEV_MODE'] = GlobalState.EXHORT_DEV_MODE;
   }
 
+  /**
+   * Authorizes the RHDA (Red Hat Dependency Analytics) service.
+   * @param context The extension context for authorization.
+   */
   async authorizeRHDA(context) {
     this.telemetryId = await getTelemetryId(context);
     process.env['VSCEXT_TELEMETRY_ID'] = this.telemetryId;
   }
 }
 
+/**
+ * The global configuration object for the extension.
+ */
 const globalConfig = new Config();
 
 export { globalConfig };

src/depOutputChannel.ts

@@ -3,25 +3,48 @@
 import * as vscode from 'vscode';
 import { Titles } from './constants';
 
+/**
+ * Class representing an output channel for displaying messages in VS Code.
+ */
 export class DepOutputChannel {
   outputChannel: vscode.OutputChannel;
+
+  /**
+   * Creates an instance of DepOutputChannel.
+   * @param channelName The name of the output channel. Defaults to the extension title.
+   */
   constructor(channelName: string = Titles.EXT_TITLE) {
     this.outputChannel = vscode.window.createOutputChannel(channelName);
   }
 
+  /**
+   * Retrieves the VS Code OutputChannel instance.
+   * Clears the channel before returning.
+   * @returns The VS Code OutputChannel instance.
+   */
   getOutputChannel(): vscode.OutputChannel {
     this.outputChannel.clear();
     return this.outputChannel;
   }
 
+  /**
+   * Shows the output channel in the VS Code UI.
+   */
   showOutputChannel(): void {
     this.outputChannel.show();
   }
 
+  /**
+   * Clears the content of the output channel.
+   */
   clearOutputChannel(): void {
     this.outputChannel.clear();
   }
 
+  /**
+   * Appends a message to the output channel.
+   * @param msg The message to append to the output channel.
+   */
   addMsgOutputChannel(msg: string): void {
     this.outputChannel.append(msg);
   }