S314-015 Added documentation using TSDoc format

Author: joaopsazevedo

integration/vscode/ada/.eslintrc.json

@@ -15,6 +15,10 @@
         },
         "project": "tsconfig.json"
     },
+    "plugins": [
+        "@typescript-eslint/eslint-plugin",
+        "eslint-plugin-tsdoc"
+    ],
     "extends": [
         "eslint:recommended",
         "plugin:@typescript-eslint/recommended",
@@ -24,5 +28,15 @@
     "ignorePatterns": [
         "out",
         "**/*.d.ts"
-    ]
-}
+    ],
+    "rules": {
+        "tsdoc/syntax": "warn",
+        "max-len": [
+            "warn",
+            {
+                "code": 100,
+                "ignoreUrls": true
+            }
+        ]
+    }
+}

integration/vscode/ada/package.json

@@ -251,6 +251,7 @@
         "eslint": "^7.30.0",
         "eslint-config-prettier": "^8.3.0",
         "eslint-plugin-prettier": "^3.4.0",
+        "eslint-plugin-tsdoc": "^0.2.14",
         "glob": "^7.1.7",
         "mocha": "^9.0.2",
         "prettier": "^2.3.2",
@@ -272,4 +273,4 @@
         "vscode-languageclient": "^7.0.0",
         "ws": "^7.5.2"
     }
-}
+}

integration/vscode/ada/src/alsExecuteCommand.ts

@@ -15,22 +15,37 @@
 -- of the license.                                                          --
 ----------------------------------------------------------------------------*/
 
+/**
+ * Implementation of a Middleware.executeCommand that intercepts and executes commands
+ */
+
 import { ExecuteCommandSignature } from 'vscode-languageclient';
 import { LanguageClient } from 'vscode-languageclient/node';
 import {
     AddParameterCommandArgs,
     alsAddParameterCommandExecutor,
 } from './refactoring/alsAddParameterCommand';
 
-type CommandExecuter = (
+/**
+ * Type alias for a function that intercepts a command and executes it by return a promise that
+ * resolve to an ExecuteCommandSignature if the command was executed successfully or undefined
+ * otherwise.
+ */
+type CommandExecutor = (
     command: string,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     args: any[],
     next: ExecuteCommandSignature
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ) => Promise<ExecuteCommandSignature | undefined>;
 
-export const alsCommandExecuter = (client: LanguageClient): CommandExecuter => {
+/**
+ * Returns a CommandExecutor that will use client to intercept and execute commands
+ *
+ * @param client - An ALS LanguageClient
+ * @returns A CommandExecutor that dispatches command to a specific executor
+ */
+export const alsCommandExecutor = (client: LanguageClient): CommandExecutor => {
     return async (
         command: string,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

integration/vscode/ada/src/alsProtocolExtensions.ts

@@ -15,34 +15,75 @@
 -- of the license.                                                          --
 ----------------------------------------------------------------------------*/
 
+/**
+ * Implementation of AdaSyntaxCheckProvider, an extension to the LSP that allows the client to send
+ * a request to the server, that checks the validity of some input according to a sert of rules
+ */
+
 import { LanguageClient } from 'vscode-languageclient/node';
 
+/**
+ * Enum with the available grammar rules for Ada. These must match the Ada_Node_Kind_Type literals
+ * defined in the Libadalang.Common package, since ALS is expected to parse the
+ * AdaSyntaxCheckRequest.rules as an array of Ada_Node_Kind_Types literals.
+ *
+ * This set is imcomplete and will rules can be added as needed.
+ */
 export enum AdaGrammarRule {
     Defining_Id_Rule = 'Defining_Id_Rule',
     Defining_Id_List_Rule = 'Defining_Id_List_Rule',
     Param_Spec_Rule = 'Param_Spec_Rule',
 }
 
+/**
+ * Structure with the data needed for the request
+ *
+ * @typeParam input - Input provided by the user
+ * @typeParam rules - Array of rules that input will be checked against to
+ */
 type AdaSyntaxCheckRequest = {
     input: string;
     rules: string[];
 };
 
+/**
+ * Structure with data responsded by the server
+ *
+ * @typeParam diagnostic - A diagnostic message in case the systax was not valid. undefined if the
+ * syntax was valid
+ */
 type AdaSyntaxCheckResponse = {
     diagnostic?: string;
 };
 
+/**
+ * Class that implements an a syntax check request as an extension to the LSP
+ */
 export class AdaSyntaxCheckProvider {
     private readonly client: LanguageClient;
     rules: string[];
     diagnostic?: string;
 
+    /**
+     * AdaSyntaxCheckProvider constructor
+     *
+     * @param client - An ALS LanguageClient
+     * @param rules - Set of rules used to check an input against
+     * @param diagnotic - And optional diagnostic message that overwrites the one sent by the server
+     */
     constructor(client: LanguageClient, rules: AdaGrammarRule[], diagnotic?: string) {
         this.client = client;
         this.rules = rules.map((rule) => rule.toString());
         this.diagnostic = diagnotic;
     }
 
+    /**
+     * Method that uses this.client to send a request to the user with
+     *
+     * @param input - Input provided by the user
+     * @returns A promise that resolves to undefined if the input is syntactically correct, or a
+     * string with a human-readable diagnostic message in case it is not.
+     */
     public sendCheckSyntaxRequest = async (input: string): Promise<undefined | string> => {
         const method = '$/alsCheckSyntax';
 

integration/vscode/ada/src/extension.ts

@@ -27,7 +27,7 @@ import * as process from 'process';
 
 import GPRTaskProvider from './gprTaskProvider';
 import gnatproveTaskProvider from './gnatproveTaskProvider';
-import { alsCommandExecuter } from './alsExecuteCommand';
+import { alsCommandExecutor } from './alsExecuteCommand';
 
 let alsTaskProvider: vscode.Disposable[] = [
     vscode.tasks.registerTaskProvider(GPRTaskProvider.gprBuildType, new GPRTaskProvider()),
@@ -63,7 +63,7 @@ export function activate(context: vscode.ExtensionContext): void {
     // Create the language client and start the client.
     const client = new LanguageClient('ada', 'Ada Language Server', serverOptions, clientOptions);
     const alsMiddleware: Middleware = {
-        executeCommand: alsCommandExecuter(client),
+        executeCommand: alsCommandExecutor(client),
     };
     client.clientOptions.middleware = alsMiddleware;
 

integration/vscode/ada/src/refactoring/alsAddParameterCommand.ts

@@ -15,21 +15,44 @@
 -- of the license.                                                          --
 ----------------------------------------------------------------------------*/
 
+/**
+ * This file contains all the constructs necessary to execute the 'als-refactor-add-parameters'
+ * command
+ */
+
 import { window, InputBoxOptions } from 'vscode';
 import { LanguageClient } from 'vscode-languageclient/node';
 
 import { AdaGrammarRule, AdaSyntaxCheckProvider } from '../alsProtocolExtensions';
 
+/* ALS will send a 'als-refactor-add-parameters' command with at least two arguments:
+ * 'newParameter' and 'requiresFullSpecification'.
+ * 'newParameter' will be filled by alsAddParameterCommandExecutor and
+ * 'requiresFullSpecification' is used to determined the syntax rules used to check if the input
+ * is valid.
+ */
 export type AddParameterCommandArgs = {
     newParameter: string;
     requiresFullSpecification: boolean;
 };
 
+/**
+ * Executes the 'als-refactor-add-parameters' command by manipulating args.newParameter with
+ * the user input. The user input is also syntactically checked, by sending a '$/alsCheckSyntax'
+ * request to ALS. This request requires a set of rules, which depend on
+ * args.requiresFullSpecification
+ *
+ * @param client - The language server client needed to interact with ALS
+ * @param args - Arguments of the 'als-refactor-add-parameters' command
+ * @returns A Promise<boolean> that resolves to true if the command was executed successfully and
+ * false otherwise
+ */
 export const alsAddParameterCommandExecutor = async (
     client: LanguageClient,
     args: AddParameterCommandArgs
 ): Promise<boolean> => {
     // If the server command attributes changed, some of args fields might be undefined
+
     if (args.requiresFullSpecification === undefined || args.newParameter === undefined) {
         return Promise.reject(
             'Invalid als-refactor-add-parameters command: missing "requiresFullSpecification" field'