Improve documentation of the GNATtest integration code

Author: eliericha

integration/vscode/ada/src/gnattest.ts

@@ -14,7 +14,9 @@ export let testRunProfile: vscode.TestRunProfile;
 
 /**
  * Types definition for the Gnattest XML file structure. The types match the XML
- * generated by src/test-mapping.adb in the libadalang-tools repository.
+ * generated by src/test-mapping.adb in the libadalang-tools repository. However
+ * these types do not describe the entire XML strutcture. Only the elements used
+ * are described.
  */
 export type Root = {
     tests_mapping: TestMapping;
@@ -34,7 +36,6 @@ type Unit = {
 type TestUnit = {
     '@_target_file': string;
     tested: Tested[];
-    dangling: Dangling;
 };
 
 type Tested = {
@@ -58,10 +59,6 @@ type Test = {
     '@_name': string;
 };
 
-type Dangling = {
-    test: Test[];
-};
-
 /**
  * The XML paths in GNATtest XML files that should always be parsed as arrays.
  * This is based the code in src/test-mapping.adb in the libadalang-tools
@@ -72,7 +69,6 @@ const alwaysArray = [
     'tests_mapping.unit.test_unit',
     'tests_mapping.unit.test_unit.tested',
     'tests_mapping.unit.test_unit.tested.test_case',
-    'tests_mapping.unit.test_unit.dangling.test',
     'tests_mapping.additional_tests',
 ];
 
@@ -133,24 +129,39 @@ async function refreshTestItemTree() {
     await addTestsRootLevel();
 }
 
+/**
+ * @returns the full path to the GNATtest XML file.
+ */
 async function getGnatTestXmlPath(): Promise<string> {
     const objDir = await getObjectDir();
     const gnatTestXmlPath = path.join(objDir, 'gnattest', 'harness', 'gnattest.xml');
     return gnatTestXmlPath;
 }
 
+/**
+ *
+ * @returns the full path to the GNATtest test driver GPR project.
+ */
 async function getGnatTestDriverProjectPath(): Promise<string> {
     const objDir = await getObjectDir();
     const testDriverPath = path.join(objDir, 'gnattest', 'harness', 'test_driver.gpr');
     return testDriverPath;
 }
 
+/**
+ *
+ * @returns the full path to the GNATtest test driver executable.
+ */
 async function getGnatTestDriverExecPath(): Promise<string> {
     const objDir = await getObjectDir();
     const testDriverPath = path.join(objDir, 'gnattest', 'harness', 'test_runner' + exe);
     return testDriverPath;
 }
 
+/**
+ * Parse the GNATtest XML file and create the top-level TestItems in the test
+ * controller for later lazy resolution.
+ */
 export async function addTestsRootLevel() {
     if (fs.existsSync(await getGnatTestXmlPath())) {
         const xmlDoc: Root = await parseGnatTestXml();
@@ -161,7 +172,10 @@ export async function addTestsRootLevel() {
     }
 }
 
-async function parseGnatTestXml() {
+/**
+ * @returns the object resulting from parsing the GNATtest XML file.
+ */
+async function parseGnatTestXml(): Promise<Root> {
     const gnatTestXmlUri = vscode.Uri.file(await getGnatTestXmlPath());
     const fileContent = await vscode.workspace.fs.readFile(gnatTestXmlUri);
     const fileContentAsBuffer = Buffer.from(fileContent);
@@ -182,9 +196,11 @@ async function parseGnatTestXml() {
     return xmlDoc;
 }
 
-/*
-    Creating nested test items to visuliaze in the view
-*/
+/**
+ * Create a TestItem for a GNATtest Unit node.
+ *
+ * @param unit - a Unit node from the GNATtest XML
+ */
 async function addUnitItem(unit: Unit) {
     const srcFile = unit['@_source_file'];
     const srcUri = await findFileInWorkspace(srcFile);
@@ -205,15 +221,25 @@ async function addUnitItem(unit: Unit) {
     }
 }
 
+/**
+ * Resolve a TestItem by computing its children node based on the GNATtest XML.
+ *
+ * @param testItem - the TestItem node
+ * @param unit - the corresponding Unit node from the GNATtest XML
+ */
 function resolveUnitItem(testItem: TestItem, unit: Unit) {
     for (const t of unit.test_unit.flatMap((u) => u.tested)) {
         addTestedItem(testItem, t);
     }
 }
 
-/*
-    Adding Test Cases to a Test Unit Item
-*/
+/**
+ * Create a TestItem corresponding to a node from the GNATtest XML. The new
+ * TestItem is added as a child of parentTestItem.
+ *
+ * @param parentTestItem - parent TestItem
+ * @param tested - the "Tested" node from the GNATtest XML
+ */
 function addTestedItem(parentTestItem: vscode.TestItem, tested: Tested) {
     const testedSubprogramName = tested['@_name'];
     const pos = new vscode.Position(
@@ -248,12 +274,25 @@ function addTestedItem(parentTestItem: vscode.TestItem, tested: Tested) {
     }
 }
 
+/**
+ * Resolve a TestItem by computing its children node based on the GNATtest XML.
+ *
+ * @param testItem - the TestItem to resolve
+ * @param tested - the corresponding "Tested" node in the GNATtest XML
+ */
 async function resolveTestedItem(testItem: TestItem, tested: Tested) {
     for (const e of tested.test_case) {
         await addTestCaseItem(testItem, e);
     }
 }
 
+/**
+ * Create a TestItem corresponding to a node from the GNATtest XML. The new
+ * TestItem is added as a child of parentTestItem.
+ *
+ * @param parentItem - the parent TestItem
+ * @param testCase - the "TestCase" node from the GNATtest XML
+ */
 async function addTestCaseItem(parentItem: vscode.TestItem, testCase: TestCase) {
     const test: Test = testCase.test;
     const testFileBasename = test['@_file'];
@@ -321,12 +360,18 @@ function createTestCaseItemId(testCase: TestCase, sourceFileName: string): strin
     return `${sourceFileName}:${testCase['@_line']}`;
 }
 
-async function findFileInWorkspace(name: string): Promise<vscode.Uri> {
-    const matchingFiles = await vscode.workspace.findFiles(`**/${name}`, undefined, 1);
+/**
+ *
+ * @param basename - a basename
+ * @returns - the Uri of the first file found in the workspace with the given basename.
+ * @throws an Error in case no matching file is found in the workspace
+ */
+async function findFileInWorkspace(basename: string): Promise<vscode.Uri> {
+    const matchingFiles = await vscode.workspace.findFiles(`**/${basename}`, undefined, 1);
     if (matchingFiles.length > 0) {
         return matchingFiles[0];
     } else {
-        throw `Source file ${name} not found in workspace`;
+        throw Error(`Source file ${basename} not found in workspace`);
     }
 }
 
@@ -405,21 +450,26 @@ async function resolveHandler(
     }
 }
 
+/**
+ * Configure the handlers needed on the test controller to support test execution.
+ *
+ * @param controller - the TestController to configure
+ */
 function configureTestExecution(controller: vscode.TestController) {
     testRunProfile = controller.createRunProfile(
         'GNATtest',
         vscode.TestRunProfileKind.Run,
         runHandler
     );
-
-    // Tests Configuration Handler to Generates Tests for a Project.
-    // testRunProfile.configureHandler = () => {
-    //     const terminal = vscode.window.createTerminal('Test Terminal');
-    //     terminal.sendText('gnattest -P ' + projectFileFullPath);
-    //     terminal.sendText('exit');
-    // };
 }
 
+/**
+ * This handler is called when the User trigger an action in the UI intended to
+ * run tests. The request might be about a subset of tests, or all tests.
+ *
+ * @param request - the request based on the User selections
+ * @param token - a cancellation token
+ */
 async function runHandler(request: vscode.TestRunRequest, token: vscode.CancellationToken) {
     if ((request.include?.length ?? 0) === 0 && (request.exclude?.length ?? 0) === 0) {
         /**
@@ -595,6 +645,13 @@ async function handleRunAll(request: vscode.TestRunRequest, token: CancellationT
     }
 }
 
+/**
+ * Invoke gprbuild on the test driver project and pipe the output into the given
+ * TestRun object.
+ *
+ * @param run - the TestRun object hosting this execution
+ * @throws an Error if the process ends with an error code
+ */
 async function buildTestDriver(run: vscode.TestRun) {
     /**
      * TODO replace this with a task invocation to capture problems
@@ -620,6 +677,16 @@ async function buildTestDriver(run: vscode.TestRun) {
     }
 }
 
+/**
+ * Decide the outcome of the given test based on the test driver output, and
+ * report it to the TestRun object.
+ *
+ * @param test - the test whose outcome must be decided
+ * @param driverOutput - the test driver standard output
+ * @param run - the TestRun object to report the outcome on
+ * @param duration - the duration of execution of the test to be reported along
+ * with the outcome, if the information is available.
+ */
 function determineTestOutcome(
     test: vscode.TestItem,
     driverOutput: string,
@@ -690,6 +757,12 @@ function determineTestOutcome(
     }
 }
 
+/**
+ *
+ * @param items - a {@link vscode.TestItemCollection}
+ * @param token - a cancellation token to stop the traversal
+ * @returns the array of leaf TestItems reachable from the given collection.
+ */
 function collectLeafsFromCollection(
     items: vscode.TestItemCollection,
     token?: CancellationToken
@@ -704,6 +777,12 @@ function collectLeafsFromCollection(
     return res;
 }
 
+/**
+ *
+ * @param item - a {@link vscode.TestItem}
+ * @param token - a cancellation token to stop the traversal
+ * @returns the array of leaf TestItems reachable from the given TestItem
+ */
 function collectLeafItems(item: TestItem, token?: CancellationToken): vscode.TestItem[] {
     if (item.children.size > 0) {
         const res: vscode.TestItem[] = [];
@@ -719,11 +798,27 @@ function collectLeafItems(item: TestItem, token?: CancellationToken): vscode.Tes
     }
 }
 
+/**
+ *
+ * @param text - a string possibly containing special RegExp characters.
+ * @returns a string where all RegExp special characters have been escaped. This
+ * can be useful when searching for an exact string which may contain special
+ * characters.
+ */
 function escapeRegExp(text: string) {
     return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
 }
 
-function logAndRun(run: vscode.TestRun, cmd: string[]) {
+/**
+ *
+ * Run a command line as a child process and pipe the output into the TestRun
+ * object managing the test execution.
+ *
+ * @param run - the TestRun object hosting the execution
+ * @param cmd - a command line to run
+ * @returns the child process object returned by {@link cp.spawnSync}
+ */
+function logAndRun(run: vscode.TestRun, cmd: string[]): cp.SpawnSyncReturns<Buffer> {
     run.appendOutput(`$ ${cmd.map((arg) => `"${arg}"`).join(' ')}\r\n`);
     return cp.spawnSync(cmd[0], cmd.slice(1));
 }