First pass at updating codebase to more consistently have function docs (#4271)

* improve documenting comments in util.ts and workflow.ts

* add command comments in triple.ts

* telemetry.ts comment updates

* shlex.ts

* schema.ts

* more comment updates for function docs

* missed some files

Author: gcampbell-msft

src/coverage.ts

@@ -8,6 +8,19 @@ const localize: nls.LocalizeFunc = nls.loadMessageBundle();
 
 const log = logging.createLogger('ctest-coverage');
 
+/**
+ * Processes coverage information files and updates the provided test run with coverage data.
+ *
+ * @param run - The test run to update with coverage data.
+ * @param coverageInfoFiles - An array of file paths to coverage information files.
+ * @param coverageData - A WeakMap to store the coverage data, mapping `vscode.FileCoverage` to an array of `vscode.FileCoverageDetail`.
+ *
+ * This function reads each coverage information file, parses its contents, and extracts coverage data for lines, branches, and functions.
+ * It then creates `vscode.FileCoverage` objects and populates them with the extracted data, including branch coverage and function declarations.
+ * The coverage data is stored in the provided `coverageData` WeakMap and added to the test run.
+ *
+ * If a coverage information file cannot be opened, a warning is logged and the file is skipped.
+ */
 export async function handleCoverageInfoFiles(run: vscode.TestRun, coverageInfoFiles: string[], coverageData: WeakMap<vscode.FileCoverage, vscode.FileCoverageDetail[]>) {
     for (const coverageInfoFile of coverageInfoFiles) {
         let contents: Uint8Array;

src/debug/cmakeDebugger/cmakeDebuggerTelemetry.ts

@@ -5,6 +5,12 @@ export enum DebugOrigin {
     originatedFromCommand = "command"
 }
 
+/**
+ * Logs telemetry data for the CMake debugger.
+ *
+ * @param origin - The origin of the telemetry event.
+ * @param debugType - The type of debugging event.
+ */
 export function logCMakeDebuggerTelemetry(origin: string, debugType: string) {
     telemetry.logEvent("cmakeDebugger", {
         origin,

src/debug/cmakeDebugger/debuggerConfigureDriver.ts

@@ -8,6 +8,17 @@ export interface DebuggerInformation {
     debuggerStoppedDueToPreconditions(message: string): void;
 }
 
+/**
+ * Generates a unique pipe name for the CMake debugger.
+ *
+ * On Windows, the pipe name is in the format:
+ * `\\.\pipe\cmake-debugger-pipe\{UUID}`
+ *
+ * On other platforms, the pipe name is in the format:
+ * `/tmp/cmake-debugger-pipe-{UUID}`
+ *
+ * @returns The unique pipe name for the CMake debugger.
+ */
 export function getDebuggerPipeName(): string {
     if (process.platform === 'win32') {
         return `\\\\.\\\\pipe\\\\cmake-debugger-pipe\\\\${uuidv4()}`;

src/debug/cmakeDebugger/debuggerScriptDriver.ts

@@ -13,6 +13,16 @@ const localize: nls.LocalizeFunc = nls.loadMessageBundle();
 const cmakeLogger = logging.createLogger('cmake');
 const scriptLogger = logging.createLogger('cmake-script');
 
+/**
+ * Executes a CMake script with the debugger.
+ *
+ * @param scriptPath - The path to the CMake script to execute.
+ * @param scriptArgs - An array of arguments to pass to the script.
+ * @param scriptEnv - A map of environment variables to set for the script.
+ * @param debuggerInformation - Information required to set up the debugger.
+ * @returns A promise that resolves when the script execution is complete.
+ * @throws Will throw an error if the script execution fails.
+ */
 export async function executeScriptWithDebugger(scriptPath: string, scriptArgs: string[], scriptEnv: Map<string, string>, debuggerInformation: DebuggerInformation): Promise<void> {
     const outputConsumer: CMakeOutputConsumer = new CMakeOutputConsumer("", scriptLogger);
 

src/debug/debugger.ts

@@ -75,6 +75,14 @@ export enum ConsoleTypes {
     newExternalWindow = 'newExternalWindow'
 }
 
+/**
+ * Creates a GDB debug configuration for VSCode.
+ *
+ * @param debuggerPath - The path to the GDB debugger executable.
+ * @param target - The executable target to be debugged.
+ * @returns A promise that resolves to a VSCode debug configuration object.
+ * @throws An error if GDB is not found in the provided path or the default search path.
+ */
 async function createGDBDebugConfiguration(debuggerPath: string, target: ExecutableTarget): Promise<VSCodeDebugConfiguration> {
     if (!await checkDebugger(debuggerPath)) {
         debuggerPath = 'gdb';
@@ -102,6 +110,14 @@ async function createGDBDebugConfiguration(debuggerPath: string, target: Executa
     };
 }
 
+/**
+ * Creates a LLDB debug configuration for VSCode.
+ *
+ * @param debuggerPath - The path to the LLDB debugger executable.
+ * @param target - The executable target to be debugged.
+ * @returns A promise that resolves to a VSCode debug configuration object.
+ * @throws An error if the debugger is not found in the specified path.
+ */
 async function createLLDBDebugConfiguration(debuggerPath: string, target: ExecutableTarget): Promise<VSCodeDebugConfiguration> {
     if (!await checkDebugger(debuggerPath)) {
         throw new Error(localize('gdb.not.found', 'Unable to find GDB in default search path and {0}.', debuggerPath));
@@ -119,6 +135,12 @@ async function createLLDBDebugConfiguration(debuggerPath: string, target: Execut
     };
 }
 
+/**
+ * Creates a Visual Studio Code debug configuration for an MSVC (Microsoft Visual C++) executable target.
+ *
+ * @param target - The executable target for which to create the debug configuration.
+ * @returns A `VSCodeDebugConfiguration` object configured for debugging the specified target.
+ */
 function createMsvcDebugConfiguration(target: ExecutableTarget): VSCodeDebugConfiguration {
     return {
         type: 'cppvsdbg',
@@ -150,6 +172,17 @@ const debuggerGenerators: DebuggerGenerators = {
     }
 };
 
+/**
+ * Searches for the compiler path in the provided CMake cache.
+ *
+ * This function iterates over a predefined list of programming languages
+ * (CXX, C, CUDA) and checks if the corresponding compiler path is present
+ * in the cache. If found, it returns the compiler path as a string.
+ * If no compiler path is found for any of the languages, it returns null.
+ *
+ * @param cache - The CMake cache to search for the compiler path.
+ * @returns The compiler path as a string if found, otherwise null.
+ */
 function searchForCompilerPathInCache(cache: CMakeCache): string | null {
     const languages = ['CXX', 'C', 'CUDA'];
     for (const lang of languages) {
@@ -162,6 +195,16 @@ function searchForCompilerPathInCache(cache: CMakeCache): string | null {
     return null;
 }
 
+/**
+ * Retrieves the debug configuration from the CMake cache for a given target and platform.
+ * @param cache - The CMake cache containing build configuration information.
+ * @param target - The executable target for which the debug configuration is being retrieved.
+ * @param platform - The platform for which the debug configuration is being retrieved (e.g., 'darwin', 'win32').
+ * @param modeOverride - Optional override for the MI mode (e.g., 'gdb', 'lldb').
+ * @param debuggerPathOverride - Optional override for the debugger path.
+ * @returns A promise that resolves to a VSCode debug configuration or null if no suitable configuration is found.
+ * @throws An error if no compiler is found in the cache.
+ */
 export async function getDebugConfigurationFromCache(cache: CMakeCache, target: ExecutableTarget, platform: string, modeOverride?: MIModes, debuggerPathOverride?: string): Promise<VSCodeDebugConfiguration | null> {
     const entry = cache.get('CMAKE_LINKER');
     if (entry !== null && !modeOverride && !debuggerPathOverride) {

src/languageServices/languageServiceData.ts

@@ -58,6 +58,15 @@ export class LanguageServiceData implements vscode.HoverProvider, vscode.Complet
         this.modules = JSON.parse(await this.getFile("modules.json", locale));
     }
 
+    /**
+     * Provides completion suggestions based on the current word and the type of language construct.
+     *
+     * @param currentWord - The current word being typed by the user.
+     * @param data - The data containing commands, modules, or variables for completion suggestions.
+     * @param type - The type of language construct (Command, Module, or Variable).
+     * @param beforeCurrentWord - Optional. The text before the current word, used to determine the appropriate snippet format.
+     * @returns An array of `vscode.CompletionItem` objects representing the completion suggestions.
+     */
     private getCompletionSuggestionsHelper(currentWord: string, data: Commands | Modules | Variables, type: LanguageType, beforeCurrentWord?: string): vscode.CompletionItem[] {
         function moduleInsertText(module: string, beforeCurrentWord?: string): vscode.SnippetString {
             if (beforeCurrentWord) {

src/schema.ts

@@ -4,6 +4,11 @@ import * as path from 'path';
 import { fs } from '@cmt/pr';
 import { thisExtensionPath } from '@cmt/util';
 
+/**
+ * Loads and compiles a JSON schema from the specified file path.
+ * @param filepath The path to the JSON schema file. Can be an absolute path or relative to the extension's root directory.
+ * @returns A promise that resolves to a ValidateFunction, which can be used to validate JSON data against the schema.
+ */
 export async function loadSchema(filepath: string): Promise<ValidateFunction> {
     const schema_path = path.isAbsolute(filepath) ? filepath : path.join(thisExtensionPath(), filepath);
     const schema_data = JSON.parse((await fs.readFile(schema_path)).toString());

src/shlex.ts

@@ -2,6 +2,13 @@ export interface ShlexOptions {
     mode: 'windows' | 'posix';
 }
 
+/**
+ * Splits a string into an iterable of tokens, similar to how a shell would parse arguments.
+ * Handles quoting and escaping according to the specified mode ('windows' or 'posix').
+ * @param str The string to split into tokens.
+ * @param opt Optional options for splitting. If not provided, defaults to the platform-specific mode ('windows' or 'posix').
+ * @returns An iterable of tokens.
+ */
 export function* split(str: string, opt?: ShlexOptions): Iterable<string> {
     opt = opt || {
         mode: process.platform === 'win32' ? 'windows' : 'posix'
@@ -70,6 +77,13 @@ export function* split(str: string, opt?: ShlexOptions): Iterable<string> {
     }
 }
 
+/**
+ * Quotes a string for safe use in a shell command.
+ * If the string contains special characters, it will be wrapped in double quotes and any existing double quotes will be escaped.
+ * @param str The string to quote.
+ * @param opt Optional options for quoting. If not provided, defaults to the platform-specific mode ('windows' or 'posix').
+ * @returns The quoted string.
+ */
 export function quote(str: string, opt?: ShlexOptions): string {
     opt = opt || {
         mode: process.platform === 'win32' ? 'windows' : 'posix'

src/telemetry.ts

@@ -61,6 +61,11 @@ export class ExperimentationTelemetry implements IExperimentationTelemetry {
 let initializationPromise: Promise<IExperimentationService> | undefined;
 let experimentationTelemetry: ExperimentationTelemetry | undefined;
 
+/**
+ * Activates the telemetry service for the extension.
+ * Initializes the experimentation service and telemetry reporter.
+ * @param extensionContext The extension context provided by VS Code.
+ */
 export function activate(extensionContext: vscode.ExtensionContext): void {
     try {
         if (extensionContext) {
@@ -76,6 +81,11 @@ export function activate(extensionContext: vscode.ExtensionContext): void {
     }
 }
 
+/**
+ * Sends telemetry data when the extension is opened.
+ * Adds the target population to the telemetry properties and logs the event.
+ * @param telemetryProperties The properties to include in the telemetry event.
+ */
 export function sendOpenTelemetry(telemetryProperties: Properties): void {
     const targetPopulation: TargetPopulation = util.getCmakeToolsTargetPopulation();
     switch (targetPopulation) {
@@ -94,10 +104,18 @@ export function sendOpenTelemetry(telemetryProperties: Properties): void {
     logEvent('open', telemetryProperties);
 }
 
+/**
+ * Gets the experimentation service instance.
+ * @returns A promise that resolves to the experimentation service instance, or undefined if not initialized.
+ */
 export function getExperimentationService(): Promise<IExperimentationService | undefined> | undefined {
     return initializationPromise;
 }
 
+/**
+ * Deactivates the telemetry service for the extension.
+ * Waits for the initialization promise to resolve and disposes of the telemetry reporter.
+ */
 export async function deactivate(): Promise<void> {
     if (initializationPromise) {
         try {
@@ -111,6 +129,12 @@ export async function deactivate(): Promise<void> {
     }
 }
 
+/**
+ * Logs a telemetry event with the specified name, properties, and measures.
+ * @param eventName The name of the event to log.
+ * @param properties Optional properties to include in the telemetry event.
+ * @param measures Optional measures to include in the telemetry event.
+ */
 export function logEvent(eventName: string, properties?: Properties, measures?: Measures): void {
     const sendTelemetry = () => {
         if (experimentationTelemetry) {
@@ -131,6 +155,12 @@ export function logEvent(eventName: string, properties?: Properties, measures?:
 
 const appInsightsKey: string =
     "0c6ae279ed8443289764825290e4f9e2-1a736e7c-1324-4338-be46-fc2a58ae4d14-7255";
+
+/**
+ * Retrieves package information for the extension.
+ * This includes the name, version, and Application Insights key.
+ * @returns An object containing the package information.
+ */
 function getPackageInfo(): IPackageInfo {
     const packageJSON: util.PackageJSON = util.thisExtensionPackage();
     return {

src/triple.ts

@@ -7,6 +7,12 @@ export interface TargetTriple {
     libc: string;
 }
 
+/**
+ * Finds the target triple from a given line of text.
+ * The target triple is a string that identifies the target architecture, vendor, and operating system.
+ * @param line The line of text to search for the target triple.
+ * @returns The target triple if found, or null if not found.
+ */
 export function findTargetTriple(line: string): string | null {
     const target_triple_re = /^Target:\s+(.*)/;
     const target_triple_match = target_triple_re.exec(line);
@@ -111,6 +117,12 @@ const TriplePossibleLibC: { key: string; regexp: RegExp }[] = [
     // otherwise system libc
 ];
 
+/**
+ * Computes the target triple string from a TargetTriple object.
+ * The target triple string identifies the target architecture, vendor, operating system, ABI, and libc.
+ * @param target The TargetTriple object containing the target information.
+ * @returns The computed target triple string.
+ */
 export function computeTargetTriple(target: TargetTriple): string {
     let triple = target.targetArch;
     if (target.vendors.length > 0) {
@@ -127,6 +139,12 @@ export function computeTargetTriple(target: TargetTriple): string {
     return triple;
 }
 
+/**
+ * Parses a target triple string into a TargetTriple object.
+ * The target triple string identifies the target architecture, vendor, operating system, ABI, and libc.
+ * @param triple The target triple string to parse.
+ * @returns A TargetTriple object with the parsed information, or undefined if parsing fails.
+ */
 export function parseTargetTriple(triple: string): TargetTriple | undefined {
     const triples = triple.split("-");
     let foundArch = 'unknown';
@@ -197,6 +215,11 @@ export function parseTargetTriple(triple: string): TargetTriple | undefined {
     };
 }
 
+/**
+ * Extracts the major version from a semantic version string.
+ * @param semver The semantic version string.
+ * @returns The major version as a string.
+ */
 export function majorVersionSemver(semver: string): string {
     const major_version_re = /^(\d+)./;
     const major_version_match = major_version_re.exec(semver);
@@ -206,6 +229,11 @@ export function majorVersionSemver(semver: string): string {
     return '';
 }
 
+/**
+ * Extracts the minor version from a semantic version string.
+ * @param semver The semantic version string.
+ * @returns The minor version as a string.
+ */
 export function minorVersionSemver(semver: string): string {
     const minor_version_re = /^(\d+).(\d+)/;
     const minor_version_match = minor_version_re.exec(semver);