Update C/C++ Documentation

- Updated the documentation for the C/C++ extension in alignment
with one of the mandates to improve documentation before the 1.0.0
release milestone.

Signed-off-by: Vincent Fugnitto <[email protected]>

packages/cpp/src/browser/cpp-build-configurations-ui.ts

@@ -129,7 +129,7 @@ export class CppBuildConfigurationChanger {
      * Lists the different options for a given root if specified, first else.
      * In this case, the options are to set/unset/create a build configuration.
      *
-     * @param root
+     * @param root the workspace root.
      */
     protected async selectCppAction(root: string | undefined): Promise<string | CppBuildConfiguration | undefined> {
         const items: QuickPickItem<'createNew' | 'reset' | CppBuildConfiguration>[] = [];

packages/cpp/src/browser/cpp-build-configurations.ts

@@ -29,11 +29,23 @@ import { deepClone } from '@theia/core';
  */
 export { CppBuildConfiguration };
 
+/**
+ * Determine if the argument is a C/C++ build configuration.
+ *
+ * @returns `true` if the argument is a C/C++ build configuration.
+ */
 // tslint:disable-next-line:no-any
 export function isCppBuildConfiguration(arg: any): arg is CppBuildConfiguration {
     return arg.name !== undefined && arg.directory !== undefined;
 }
 
+/**
+ * Determine if two C/C++ build configurations are equal.
+ * @param a the first C/C++ build configuration.
+ * @param b the second C/C++ build configuration.
+ *
+ * @returns `true` if both `a` and `b` are equal.
+ */
 export function equals(a: CppBuildConfiguration, b: CppBuildConfiguration): boolean {
     return (
         a.name === b.name &&
@@ -50,6 +62,10 @@ class SavedActiveBuildConfigurations {
 }
 
 export const CppBuildConfigurationManager = Symbol('CppBuildConfigurationManager');
+
+/**
+ * Representation of a C/C++ build configuration manager.
+ */
 export interface CppBuildConfigurationManager {
 
     /**
@@ -176,6 +192,9 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
 
     public ready: Promise<void>;
 
+    /**
+     * Initialize the manager.
+     */
     @postConstruct()
     async init(): Promise<void> {
         // Try to read the active build config from local storage.
@@ -191,6 +210,12 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
         });
     }
 
+    /**
+     * Get the C/C++ build configuration from the preferences.
+     * @param root the optional workspace root.
+     *
+     * @returns an array of build configurations.
+     */
     protected getConfigsFromPreferences(root?: string): CppBuildConfiguration[] {
         if (root) {
             return Array.from(this.cppPreferences.get(CPP_BUILD_CONFIGURATIONS_PREFERENCE_KEY, [], root));
@@ -270,6 +295,12 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
         return a.name === b.name && a.directory === b.directory;
     }
 
+    /**
+     * Get the active build configuration.
+     * @param root the optional workspace root.
+     *
+     * @returns the active build configuration if it exists, else `undefined`.
+     */
     getActiveConfig(root?: string): CppBuildConfiguration | undefined {
         // Get the active workspace root for the given uri, else for the first workspace root.
         const workspaceRoot = this.getRoot(root);
@@ -279,10 +310,22 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
         return this.activeConfigurations.get(workspaceRoot);
     }
 
+    /**
+     * Get all active build configurations.
+     * - If for a given root the build configuration is `undefined`, the root does not contain
+     * an active build configuration.
+     *
+     * @returns the map of all active configurations if available, for each workspace root.
+     */
     getAllActiveConfigs(): Map<string, CppBuildConfiguration | undefined> {
         return this.activeConfigurations;
     }
 
+    /**
+     * Set the active build configuration.
+     * @param config the build configuration to be set. If `undefined` there will be no active configuration.
+     * @param root the optional workspace root. If unprovided, fallback to the first workspace root if available.
+     */
     setActiveConfig(config: CppBuildConfiguration | undefined, root?: string): void {
         // Set the active workspace root for the given uri, else for the first workspace root.
         const workspaceRoot = this.getRoot(root);
@@ -311,6 +354,12 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
         return this.activeConfigChange2Emitter.event;
     }
 
+    /**
+     * Get all build configurations.
+     * @param root the optional workspace root.
+     *
+     * @returns an array of build configurations.
+     */
     getConfigs(root?: string): CppBuildConfiguration[] {
         const workspaceRoot = this.getRoot(root);
         if (!workspaceRoot) {
@@ -323,19 +372,32 @@ export class CppBuildConfigurationManagerImpl implements CppBuildConfigurationMa
         return configs;
     }
 
+    /**
+     * Get all valid build configurations.
+     * @param root the optional workspace root.
+     *
+     * @returns an array of build configurations.
+     */
     getValidConfigs(root?: string): CppBuildConfiguration[] {
         return this.getConfigs(root)
             .filter(a => a.name !== '' && a.directory !== '')
             .sort((a, b) => (a.name.localeCompare(b.name)));
     }
 
     /**
-     * @todo Optimize by caching the merge result, based on the `CppBuildConfiguration.directory` field?
+     * Get the merged compilation database.
      */
     async getMergedCompilationDatabase(params: { directories: string[] }): Promise<string> {
+        // TODO: Optimize by caching the merge result, based on the `CppBuildConfiguration.directory` field?
         return this.buildConfigurationServer.getMergedCompilationDatabase(params);
     }
 
+    /**
+     * Get the root directory.
+     * @param root the optional workspace root.
+     *
+     * @returns the root directory if it is present, else `undefined`.
+     */
     protected getRoot(root?: string): string | undefined {
         if (root) {
             return root;

packages/cpp/src/browser/cpp-commands.ts

@@ -27,10 +27,13 @@ import { HEADER_AND_SOURCE_FILE_EXTENSIONS } from '../common';
 import { ExecuteCommandRequest, ExecuteCommandParams } from 'vscode-languageserver-protocol';
 import { CppPreferences } from './cpp-preferences';
 
+/**
+ * The C/C++ command category.
+ */
 const CPP_CATEGORY = 'C/C++';
 
 /**
- * Switch between source/header file
+ * Command to switch between source/header files.
  */
 export const SWITCH_SOURCE_HEADER: Command = {
     id: 'switch_source_header',
@@ -39,40 +42,62 @@ export const SWITCH_SOURCE_HEADER: Command = {
 };
 
 /**
- * A command that is used to show the references from a CodeLens.
+ * Command that is used to show the references from a CodeLens.
  */
 export const SHOW_CLANGD_REFERENCES: Command = {
     id: 'clangd.references'
 };
 
+/**
+ * Command to dump file inclusions.
+ */
 export const DUMP_INCLUSIONS: Command = {
     id: 'clangd.dumpinclusions',
     category: CPP_CATEGORY,
     label: 'Dump File Inclusions (Debug)',
 };
 
+/**
+ * Command to dump files included the active file.
+ */
 export const DUMP_INCLUDED_BY: Command = {
     id: 'clangd.dumpincludedby',
     category: CPP_CATEGORY,
     label: 'Dump Files Including this File (Debug)',
 };
 
+/**
+ * Command to re-index the workspace.
+ */
 export const REINDEX: Command = {
     id: 'clangd.reindex',
     category: CPP_CATEGORY,
     label: 'Reindex Workspace (Debug)',
 };
 
+/**
+ * Command to print index statistics.
+ */
 export const PRINT_STATS: Command = {
     id: 'clangd.printstats',
     category: CPP_CATEGORY,
     label: 'Print Index Statistics (Debug)',
 };
 
+/**
+ * Command to open the file path.
+ * @param path the file path.
+ */
 export const FILE_OPEN_PATH = (path: string): Command => <Command>{
     id: 'file:openPath'
 };
 
+/**
+ * Determine if a C/C++ file is currently active (opened).
+ * @param editorManager the editor manager if it is defined.
+ *
+ * @returns `true` if the current active editor is a C/C++ file.
+ */
 export function editorContainsCppFiles(editorManager: EditorManager | undefined): boolean {
     if (editorManager && editorManager.activeEditor) {
         const uri = editorManager.activeEditor.editor.document.uri;
@@ -92,7 +117,6 @@ export class CppCommandContribution implements CommandContribution {
         @inject(OpenerService) protected readonly openerService: OpenerService,
         @inject(EditorManager) private editorService: EditorManager,
         protected readonly selectionService: SelectionService
-
     ) { }
 
     registerCommands(commands: CommandRegistry): void {
@@ -122,6 +146,9 @@ export class CppCommandContribution implements CommandContribution {
         });
     }
 
+    /**
+     * Actually switch the source header.
+     */
     protected async switchSourceHeader(): Promise<void> {
         const uri = UriSelection.getUri(this.selectionService.selection);
         if (!uri) {
@@ -135,6 +162,9 @@ export class CppCommandContribution implements CommandContribution {
         }
     }
 
+    /**
+     * Actually dump file inclusions.
+     */
     private async dumpInclusions(): Promise<void> {
         const uri = UriSelection.getUri(this.selectionService.selection);
         if (!uri) {
@@ -146,6 +176,9 @@ export class CppCommandContribution implements CommandContribution {
         languageClient.sendRequest(ExecuteCommandRequest.type, params);
     }
 
+    /**
+     * Actually dump files including the active file.
+     */
     private async dumpIncludedBy(): Promise<void> {
         const uri = UriSelection.getUri(this.selectionService.selection);
         if (!uri) {
@@ -157,12 +190,18 @@ export class CppCommandContribution implements CommandContribution {
         languageClient.sendRequest(ExecuteCommandRequest.type, params);
     }
 
+    /**
+     * Actually perform re-index.
+     */
     private async reindex(): Promise<void> {
         const params: ExecuteCommandParams = { command: REINDEX.id };
         const languageClient = await this.clientContribution.languageClient;
         languageClient.sendRequest(ExecuteCommandRequest.type, params);
     }
 
+    /**
+     * Actually perform print stats.
+     */
     private async printStats(): Promise<void> {
         const params: ExecuteCommandParams = { command: PRINT_STATS.id };
         const languageClient = await this.clientContribution.languageClient;

packages/cpp/src/browser/cpp-keybinding.ts

@@ -28,6 +28,13 @@ export class CppKeybindingContext implements KeybindingContext {
 
     id = 'cpp.keybinding.context';
 
+    /**
+     * Determine if the keybinding is enabled.
+     * The keybinding is enabled if the editor currently contains an active C/C++ file.
+     * @param arg the keybinding.
+     *
+     * @returns `true` if the keybinding is enabled.
+     */
     isEnabled(arg: Keybinding): boolean {
         return editorContainsCppFiles(this.editorService);
     }
@@ -40,6 +47,10 @@ export class CppKeybindingContribution implements KeybindingContribution {
         @inject(CppKeybindingContext) protected readonly cppKeybindingContext: CppKeybindingContext
     ) { }
 
+    /**
+     * Register keybindings.
+     * @param registry the keybinding registry.
+     */
     registerKeybindings(registry: KeybindingRegistry): void {
         [
             {