autogen docs

terminus-terminal/src/api.ts

@@ -1,10 +1,18 @@
 import { BaseTerminalTabComponent } from './components/baseTerminalTab.component'
 
+/**
+ * Extend to automatically run actions on new terminals
+ */
 export abstract class TerminalDecorator {
-    // tslint:disable-next-line no-empty
-    attach (_terminal: BaseTerminalTabComponent): void { }
-    // tslint:disable-next-line no-empty
-    detach (_terminal: BaseTerminalTabComponent): void { }
+    /**
+     * Called when a new terminal tab starts
+     */
+    attach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty
+
+    /**
+     * Called before a terminal tab is destroyed
+     */
+    detach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty
 }
 
 export interface ResizeEvent {
@@ -17,7 +25,7 @@ export interface SessionOptions {
     command: string
     args: string[]
     cwd?: string
-    env?: any
+    env?: {[id: string]: string}
     width?: number
     height?: number
     pauseAfterExit?: boolean
@@ -37,10 +45,16 @@ export interface ITerminalColorScheme {
     colors: string[]
 }
 
+/**
+ * Extend to add more terminal color schemes
+ */
 export abstract class TerminalColorSchemeProvider {
     abstract async getSchemes (): Promise<ITerminalColorScheme[]>
 }
 
+/**
+ * Extend to add more terminal context menu items
+ */
 export abstract class TerminalContextMenuItemProvider {
     weight: number
 
@@ -52,10 +66,18 @@ export interface IShell {
     name?: string
     command: string
     args?: string[]
-    env?: any
+    env?: {[id: string]: string}
+
+    /**
+     * Base path to which shell's internal FS is relative
+     * Currently used for WSL only
+     */
     fsBase?: string
 }
 
+/**
+ * Extend to add support for more shells
+ */
 export abstract class ShellProvider {
     abstract async provide (): Promise<IShell[]>
 }

terminus-terminal/src/components/baseTerminalTab.component.ts

@@ -10,29 +10,43 @@ import { TerminalFrontendService } from '../services/terminalFrontend.service'
 import { TerminalDecorator, ResizeEvent, TerminalContextMenuItemProvider } from '../api'
 import { Frontend } from '../frontends/frontend'
 
+/**
+ * A class to base your custom terminal tabs on
+ */
 export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit, OnDestroy {
     static template = `
         <div
             #content
             class="content"
-            [style.opacity]="htermVisible ? 1 : 0"
+            [style.opacity]="frontendIsReady ? 1 : 0"
         ></div>
     `
     static styles = [require('./terminalTab.component.scss')]
 
     session: BaseSession
     @Input() zoom = 0
+
+    /** @hidden */
     @ViewChild('content') content
+
+    /** @hidden */
     @HostBinding('style.background-color') backgroundColor: string
+
+    /** @hidden */
     @HostBinding('class.top-padded') topPadded: boolean
+
     frontend: Frontend
-    sessionCloseSubscription: Subscription
-    hotkeysSubscription: Subscription
-    htermVisible = false
+
+    /** @hidden */
+    frontendIsReady = false
+
     frontendReady = new Subject<void>()
     size: ResizeEvent
+
     protected logger: Logger
     protected output = new Subject<string>()
+    private sessionCloseSubscription: Subscription
+    private hotkeysSubscription: Subscription
     private bellPlayer: HTMLAudioElement
     private termContainerSubscriptions: Subscription[] = []
 
@@ -122,6 +136,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.contextMenuProviders.sort((a, b) => a.weight - b.weight)
     }
 
+    /** @hidden */
     ngOnInit () {
         this.focused$.subscribe(() => {
             this.configure()
@@ -131,7 +146,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.frontend = this.terminalContainersService.getFrontend(this.session)
 
         this.frontend.ready$.subscribe(() => {
-            this.htermVisible = true
+            this.frontendIsReady = true
         })
 
         this.frontend.resize$.pipe(first()).subscribe(async ({ columns, rows }) => {
@@ -191,14 +206,14 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         return items
     }
 
-    detachTermContainerHandlers () {
+    protected detachTermContainerHandlers () {
         for (let subscription of this.termContainerSubscriptions) {
             subscription.unsubscribe()
         }
         this.termContainerSubscriptions = []
     }
 
-    attachTermContainerHandlers () {
+    protected attachTermContainerHandlers () {
         this.detachTermContainerHandlers()
 
         const maybeConfigure = () => {
@@ -274,6 +289,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         ]
     }
 
+    /**
+     * Feeds input into the active session
+     */
     sendInput (data: string) {
         this.session.write(data)
         if (this.config.store.terminal.scrollOnInput) {
@@ -281,6 +299,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         }
     }
 
+    /**
+     * Feeds input into the terminal frontend
+     */
     write (data: string) {
         let percentageMatch = /(^|[^\d])(\d+(\.\d+)?)%([^\d]|$)/.exec(data)
         if (percentageMatch) {
@@ -308,6 +329,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.sendInput(data)
     }
 
+    /**
+     * Applies the user settings to the terminal
+     */
     configure (): void {
         this.frontend.configure()
 
@@ -339,6 +363,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.frontend.setZoom(this.zoom)
     }
 
+    /** @hidden */
     ngOnDestroy () {
         this.frontend.detach(this.content.nativeElement)
         this.detachTermContainerHandlers()

terminus-terminal/src/components/terminalTab.component.ts

@@ -5,6 +5,7 @@ import { BaseTerminalTabComponent } from './baseTerminalTab.component'
 import { SessionOptions } from '../api'
 import { Session } from '../services/sessions.service'
 
+/** @hidden */
 @Component({
     selector: 'terminalTab',
     template: BaseTerminalTabComponent.template,

terminus-terminal/src/frontends/frontend.ts

@@ -2,6 +2,9 @@ import { Observable, Subject, AsyncSubject, ReplaySubject, BehaviorSubject } fro
 import { ResizeEvent } from '../api'
 import { ConfigService, ThemesService } from 'terminus-core'
 
+/**
+ * Extend to add support for a different VT frontend implementation
+ */
 export abstract class Frontend {
     configService: ConfigService
     themesService: ThemesService

terminus-terminal/src/services/sessions.service.ts

@@ -10,16 +10,13 @@ import { exec } from 'mz/child_process'
 import { SessionOptions } from '../api'
 import { WIN_BUILD_CONPTY_SUPPORTED, isWindowsBuild } from '../utils'
 
-let macOSNativeProcessList
 try {
-    macOSNativeProcessList = require('macos-native-processlist')
-} catch (e) { } // tslint:disable-line
+    var macOSNativeProcessList = require('macos-native-processlist') // tslint:disable-line
+} catch { } // tslint:disable-line
 
-let windowsProcessTree
 try {
-    windowsProcessTree = require('windows-process-tree')
-} catch (e) {
-} // tslint:disable-line
+    var windowsProcessTree = require('windows-process-tree') // tslint:disable-line
+} catch { } // tslint:disable-line
 
 export interface IChildProcess {
     pid: number
@@ -31,6 +28,10 @@ const windowsDirectoryRegex = /([a-zA-Z]:[^\:\[\]\?\"\<\>\|]+)/mi // tslint:dis
 const OSC1337Prefix = '\x1b]1337;'
 const OSC1337Suffix = '\x07'
 
+/**
+ * A session object for a [[BaseTerminalTabComponent]]
+ * Extend this to implement custom I/O and process management for your terminal tab
+ */
 export abstract class BaseSession {
     open: boolean
     name: string
@@ -59,10 +60,10 @@ export abstract class BaseSession {
         this.initialDataBuffer = null
     }
 
-    abstract start (options: SessionOptions)
-    abstract resize (columns, rows)
-    abstract write (data)
-    abstract kill (signal?: string)
+    abstract start (options: SessionOptions): void
+    abstract resize (columns: number, rows: number): void
+    abstract write (data: string): void
+    abstract kill (signal?: string): void
     abstract async getChildProcesses (): Promise<IChildProcess[]>
     abstract async gracefullyKillProcess (): Promise<void>
     abstract async getWorkingDirectory (): Promise<string>

terminus-terminal/src/services/terminal.service.ts

@@ -11,8 +11,12 @@ export class TerminalService {
     private shells = new AsyncSubject<IShell[]>()
     private logger: Logger
 
+    /**
+     * A fresh list of all available shells
+     */
     get shells$ (): Observable<IShell[]> { return this.shells }
 
+    /** @hidden */
     constructor (
         private app: AppService,
         private config: ConfigService,
@@ -28,12 +32,12 @@ export class TerminalService {
         })
     }
 
-    async getShells (): Promise<IShell[]> {
+    private async getShells (): Promise<IShell[]> {
         let shellLists = await Promise.all(this.config.enabledServices(this.shellProviders).map(x => x.provide()))
         return shellLists.reduce((a, b) => a.concat(b), [])
     }
 
-    async reloadShells () {
+    private async reloadShells () {
         this.shells = new AsyncSubject<IShell[]>()
         let shells = await this.getShells()
         this.logger.debug('Shells list:', shells)
@@ -41,6 +45,10 @@ export class TerminalService {
         this.shells.complete()
     }
 
+    /**
+     * Launches a new terminal with a specific shell and CWD
+     * @param pause Wait for a keypress when the shell exits
+     */
     async openTab (shell?: IShell, cwd?: string, pause?: boolean): Promise<TerminalTabComponent> {
         if (cwd && !fs.existsSync(cwd)) {
             console.warn('Ignoring non-existent CWD:', cwd)
@@ -76,6 +84,9 @@ export class TerminalService {
         }
     }
 
+    /**
+     * Open a terminal with custom session options
+     */
     openTabWithOptions (sessionOptions: SessionOptions): TerminalTabComponent {
         if (sessionOptions.runAsAdministrator && this.uac.isAvailable) {
             sessionOptions = this.uac.patchSessionOptionsForUAC(sessionOptions)

terminus-terminal/src/services/terminalFrontend.service.ts

@@ -9,6 +9,7 @@ import { BaseSession } from '../services/sessions.service'
 export class TerminalFrontendService {
     private containers = new WeakMap<BaseSession, Frontend>()
 
+    /** @hidden */
     constructor (private config: ConfigService, private themes: ThemesService) { }
 
     getFrontend (session?: BaseSession): Frontend {