external-terminal: update documentation

The following commit updates the documentation for `external-terminal`:
- updates the `readme`.
- includes additional method documentation.
- includes additional interface documentation.

Signed-off-by: vince-fugnitto <vincent.fugnitto@ericsson.com>

packages/external-terminal/README.md

@@ -12,10 +12,24 @@
 
 ## Description
 
-The `@theia/external-terminal` extension contributes the ability to spawn external terminals from `electron` applications.
+The `@theia/external-terminal` extension contributes the ability to spawn external terminals for `electron` applications.
+The extension includes the necessary logic to spawn the appropriate terminal application for each operating system (Windows, Linux, OSX)
+by identifying certain environment variables. The extension also contributes preferences to control this behavior if necessary.
 
 **Note:** The extension does not support browser applications.
 
+## Contributions
+
+### Commands
+
+- `OPEN_NATIVE_CONSOLE`: spawns an external terminal (native console) for different use-cases.
+
+### Preferences
+
+- `terminal.external.windowsExec`: the application executable for Windows.
+- `terminal.external.linuxExec`: the application executable for Linux.
+- `terminal.external.osxExec`: the application executable for OSX.
+
 ## Additional Information
 
 - [Theia - GitHub](https://github.com/eclipse-theia/theia)

packages/external-terminal/src/common/external-terminal.ts

@@ -17,10 +17,22 @@
 export const ExternalTerminalService = Symbol('ExternalTerminalService');
 export const externalTerminalServicePath = '/services/external-terminal';
 
+/**
+ * Represents the external terminal configuration options.
+ */
 export interface ExternalTerminalConfiguration {
-    'terminal.external.windowsExec': string
-    'terminal.external.osxExec': string
-    'terminal.external.linuxExec': string
+    /**
+     * The external terminal executable for Windows.
+     */
+    'terminal.external.windowsExec': string;
+    /**
+     * The external terminal executable for OSX.
+     */
+    'terminal.external.osxExec': string;
+    /**
+     * The external terminal executable for Linux.
+     */
+    'terminal.external.linuxExec': string;
 }
 
 export interface ExternalTerminalService {
@@ -34,9 +46,9 @@ export interface ExternalTerminalService {
     openTerminal(configuration: ExternalTerminalConfiguration, cwd: string): Promise<void>;
 
     /**
-     * Determine the default exec of the external terminal.
+     * Get the default executable.
      *
-     * @returns the default terminal exec.
+     * @returns the default terminal executable.
      */
     getDefaultExec(): Promise<string>;
 

packages/external-terminal/src/electron-browser/external-terminal-contribution.ts

@@ -15,18 +15,10 @@
  ********************************************************************************/
 
 import { inject, injectable } from 'inversify';
-import {
-    Command,
-    CommandContribution,
-    CommandRegistry
-} from '@theia/core/lib/common';
+import { Command, CommandContribution, CommandRegistry } from '@theia/core/lib/common';
 import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
 import { QuickPickService } from '@theia/core/lib/common/quick-pick-service';
-import {
-    KeybindingContribution,
-    KeybindingRegistry,
-    LabelProvider
-} from '@theia/core/lib/browser';
+import { KeybindingContribution, KeybindingRegistry, LabelProvider } from '@theia/core/lib/browser';
 import { EditorManager } from '@theia/editor/lib/browser/editor-manager';
 import { WorkspaceService } from '@theia/workspace/lib/browser';
 import { ExternalTerminalService } from '../common/external-terminal';
@@ -79,10 +71,10 @@ export class ExternalTerminalFrontendContribution implements CommandContribution
     /**
      * Open a native console on the host machine.
      *
-     * If multi-root workspace is open, displays a quick pick to let users choose which workspace to spawn the terminal.
-     * If only one workspace is open, the terminal spawns at the root of the current workspace.
-     * If no workspace is open and there is an active editor, the terminal spawns at the parent folder of that file.
-     * If no workspace is open and there are no active editors, the terminal spawns at user home directory.
+     * - If multi-root workspace is open, displays a quick pick to let users choose which workspace to spawn the terminal.
+     * - If only one workspace is open, the terminal spawns at the root of the current workspace.
+     * - If no workspace is open and there is an active editor, the terminal spawns at the parent folder of that file.
+     * - If no workspace is open and there are no active editors, the terminal spawns at user home directory.
      */
     protected async openExternalTerminal(): Promise<void> {
         const configuration = this.externalTerminalPreferences.getExternalTerminalConfiguration();

packages/external-terminal/src/electron-browser/external-terminal-frontend-module.ts

@@ -16,10 +16,7 @@
 
 import { ContainerModule, interfaces } from 'inversify';
 import { CommandContribution } from '@theia/core/lib/common';
-import {
-    KeybindingContribution,
-    WebSocketConnectionProvider
-} from '@theia/core/lib/browser';
+import { KeybindingContribution, WebSocketConnectionProvider } from '@theia/core/lib/browser';
 import { bindExternalTerminalPreferences } from './external-terminal-preference';
 import { ExternalTerminalFrontendContribution } from './external-terminal-contribution';
 import { ExternalTerminalService, externalTerminalServicePath } from '../common/external-terminal';

packages/external-terminal/src/electron-node/external-terminal-backend-module.ts

@@ -23,9 +23,8 @@ import { LinuxExternalTerminalService } from './linux-external-terminal-service'
 import { WindowsExternalTerminalService } from './windows-external-terminal-service';
 
 export function bindExternalTerminalService(bind: interfaces.Bind): void {
-    const serviceProvider: interfaces.ServiceIdentifier<ExternalTerminalService> = isWindows ? WindowsExternalTerminalService
-        : isOSX ? MacExternalTerminalService
-            : LinuxExternalTerminalService;
+    const serviceProvider: interfaces.ServiceIdentifier<ExternalTerminalService> =
+        isWindows ? WindowsExternalTerminalService : isOSX ? MacExternalTerminalService : LinuxExternalTerminalService;
     bind(serviceProvider).toSelf().inSingletonScope();
     bind(ExternalTerminalService).toService(serviceProvider);
 

packages/external-terminal/src/electron-node/linux-external-terminal-service.ts

@@ -35,7 +35,19 @@ export class LinuxExternalTerminalService implements ExternalTerminalService {
         await this.spawnTerminal(configuration, FileUri.fsPath(cwd));
     }
 
-    private async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+    async getDefaultExec(): Promise<string> {
+        return LinuxExternalTerminalService.getDefaultTerminalLinux();
+    }
+
+    /**
+     * Spawn the external terminal for the given options.
+     * - The method spawns the terminal application based on the preferences, else uses the default value.
+     * @param configuration the preference configuration.
+     * @param cwd the optional current working directory to spawn from.
+     */
+    protected async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+
+        // Use the executable value from the preferences if available, else fallback to the default.
         const terminalConfig = configuration['terminal.external.linuxExec'];
         const execPromise = terminalConfig ? Promise.resolve(terminalConfig) : LinuxExternalTerminalService.getDefaultTerminalLinux();
 
@@ -49,13 +61,11 @@ export class LinuxExternalTerminalService implements ExternalTerminalService {
         });
     }
 
-    async getDefaultExec(): Promise<string> {
-        return LinuxExternalTerminalService.getDefaultTerminalLinux();
-    }
-
     /**
-     * Get the default terminal app on Linux.
-     * (determine and initialize the variable based on desktop environment if not found)
+     * Get the default terminal application on Linux.
+     * - The following method uses environment variables to identify the best default possible for each distro.
+     *
+     * @returns the default application on Linux.
      */
     protected static async getDefaultTerminalLinux(): Promise<string> {
         if (!LinuxExternalTerminalService.DEFAULT_TERMINAL_LINUX_READY) {

packages/external-terminal/src/electron-node/mac-external-terminal-service.ts

@@ -34,9 +34,22 @@ export class MacExternalTerminalService implements ExternalTerminalService {
         await this.spawnTerminal(configuration, FileUri.fsPath(cwd));
     }
 
-    private async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+    async getDefaultExec(): Promise<string> {
+        return MacExternalTerminalService.getDefaultTerminalOSX();
+    }
+
+    /**
+     * Spawn the external terminal for the given options.
+     * - The method spawns the terminal application based on the preferences, else uses the default value.
+     * @param configuration the preference configuration.
+     * @param cwd the optional current working directory to spawn from.
+     */
+    protected async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+
+        // Use the executable value from the preferences if available, else fallback to the default.
         const terminalConfig = configuration['terminal.external.osxExec'];
         const terminalApp = terminalConfig || MacExternalTerminalService.getDefaultTerminalOSX();
+
         return new Promise<void>((resolve, reject) => {
             const args = ['-a', terminalApp];
             if (cwd) {
@@ -48,10 +61,6 @@ export class MacExternalTerminalService implements ExternalTerminalService {
         });
     }
 
-    async getDefaultExec(): Promise<string> {
-        return MacExternalTerminalService.getDefaultTerminalOSX();
-    }
-
     /**
      * Get the default terminal app on OSX.
      */

packages/external-terminal/src/electron-node/windows-external-terminal-service.ts

@@ -35,7 +35,19 @@ export class WindowsExternalTerminalService implements ExternalTerminalService {
         await this.spawnTerminal(configuration, FileUri.fsPath(cwd));
     }
 
-    private async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+    async getDefaultExec(): Promise<string> {
+        return WindowsExternalTerminalService.getDefaultTerminalWindows();
+    }
+
+    /**
+     * Spawn the external terminal for the given options.
+     * - The method spawns the terminal application based on the preferences, else uses the default value.
+     * @param configuration the preference configuration.
+     * @param cwd the optional current working directory to spawn from.
+     */
+    protected async spawnTerminal(configuration: ExternalTerminalConfiguration, cwd?: string): Promise<void> {
+
+        // Use the executable value from the preferences if available, else fallback to the default.
         const terminalConfig = configuration['terminal.external.windowsExec'];
         const exec = terminalConfig || WindowsExternalTerminalService.getDefaultTerminalWindows();
 
@@ -74,13 +86,11 @@ export class WindowsExternalTerminalService implements ExternalTerminalService {
         });
     }
 
-    async getDefaultExec(): Promise<string> {
-        return WindowsExternalTerminalService.getDefaultTerminalWindows();
-    }
-
     /**
-     * Get the default terminal app on Windows.
-     * (determine and initialize the variable if not found).
+     * Get the default terminal application on Windows.
+     * - The following method uses environment variables to identify the best default possible value.
+     *
+     * @returns the default application on Windows.
      */
     protected static getDefaultTerminalWindows(): string {
         if (!WindowsExternalTerminalService.DEFAULT_TERMINAL_WINDOWS) {
@@ -91,7 +101,7 @@ export class WindowsExternalTerminalService implements ExternalTerminalService {
     }
 
     /**
-     * Find the Windows Shell process to start up (default to cmd.exe).
+     * Find the Windows Shell process to start up (defaults to cmd.exe).
      */
     protected getWindowsShell(): string {
         // Find the path to cmd.exe if possible (%compsec% environment variable).