Add eslint-plugin-jsdoc and enable check-param-names

.eslintrc.json

@@ -39,7 +39,8 @@
     "**/*.js"
   ],
   "plugins": [
-    "@typescript-eslint"
+    "@typescript-eslint",
+    "jsdoc"
   ],
   "rules": {
     "no-extra-semi": "error",
@@ -141,6 +142,7 @@
       "warn",
       "always"
     ],
+    "jsdoc/check-param-names": 1,
     "keyword-spacing": "warn",
     "new-parens": "warn",
     "no-duplicate-imports": "warn",

addons/xterm-addon-canvas/src/BaseRenderLayer.ts

@@ -11,7 +11,7 @@ import { throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
 import { IRasterizedGlyph, IRenderDimensions, ISelectionRenderModel, ITextureAtlas } from 'browser/renderer/shared/Types';
 import { createSelectionRenderModel } from 'browser/renderer/shared/SelectionRenderModel';
 import { ICoreBrowserService, IThemeService } from 'browser/services/Services';
-import { IColorSet, ReadonlyColorSet } from 'browser/Types';
+import { ReadonlyColorSet } from 'browser/Types';
 import { CellData } from 'common/buffer/CellData';
 import { WHITESPACE_CELL_CODE } from 'common/buffer/Constants';
 import { IBufferService, IDecorationService, IOptionsService } from 'common/services/Services';
@@ -329,7 +329,6 @@ export abstract class BaseRenderLayer extends Disposable implements IRenderLayer
    * @param cell The cell data for the character to draw.
    * @param x The column to draw at.
    * @param y The row to draw at.
-   * @param color The color of the character.
    */
   protected _fillCharTrueColor(cell: CellData, x: number, y: number): void {
     this._ctx.font = this._getFont(false, false);

addons/xterm-addon-search/src/SearchAddon.ts

@@ -477,7 +477,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
    * started on an earlier line then it is skipped since it will be properly searched when the terminal line that the
    * text starts on is searched.
    * @param term The search term.
-   * @param position The position to start the search.
+   * @param searchPosition The position to start the search.
    * @param searchOptions Search options.
    * @param isReverseSearch Whether the search should start from the right side of the terminal and search to the left.
    * @return The search result if it was found.
@@ -627,7 +627,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
    * Wide characters will count as two columns in the resulting string. This
    * function is useful for getting the actual text underneath the raw selection
    * position.
-   * @param line The line being translated.
+   * @param lineIndex The index of the line being translated.
    * @param trimRight Whether to trim whitespace to the right.
    */
   private _translateBufferLineToStringWithWrap(lineIndex: number, trimRight: boolean): LineCacheEntry {
@@ -702,10 +702,10 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
   }
 
   /**
-   * Applies styles to the decoration when it is rendered
-   * @param element the decoration's element
-   * @param backgroundColor the background color to apply
-   * @param borderColor the border color to apply
+   * Applies styles to the decoration when it is rendered.
+   * @param element The decoration's element.
+   * @param borderColor The border color to apply.
+   * @param isActiveResult Whether the element is part of the active search result.
    * @returns
    */
   private _applyStyles(element: HTMLElement, borderColor: string | undefined, isActiveResult: boolean): void {

addons/xterm-addon-web-links/src/WebLinkProvider.ts

@@ -105,9 +105,8 @@ export class LinkComputer {
 
   /**
    * Gets the entire line for the buffer line
-   * @param line The line being translated.
+   * @param lineIndex The index of the line being translated.
    * @param trimRight Whether to trim whitespace to the right.
-   * @param terminal The terminal
    */
   private static _translateBufferLineToStringWithWrap(lineIndex: number, trimRight: boolean, terminal: Terminal): [string, number] {
     let lineString = '';

addons/xterm-addon-webgl/src/WebglRenderer.ts

@@ -254,8 +254,6 @@ export class WebglRenderer extends Disposable implements IRenderer {
 
   /**
    * Refreshes the char atlas, aquiring a new one if necessary.
-   * @param terminal The terminal.
-   * @param colorSet The color set to use for the char atlas.
    */
   private _refreshCharAtlas(): void {
     if (this.dimensions.scaledCharWidth <= 0 && this.dimensions.scaledCharHeight <= 0) {

addons/xterm-addon-webgl/src/renderLayer/BaseRenderLayer.ts

@@ -221,7 +221,6 @@ export abstract class BaseRenderLayer extends Disposable implements IRenderLayer
    * @param cell The cell data for the character to draw.
    * @param x The column to draw at.
    * @param y The row to draw at.
-   * @param color The color of the character.
    */
   protected _fillCharTrueColor(terminal: Terminal, cell: CellData, x: number, y: number): void {
     this._ctx.font = this._getFont(terminal, false, false);

demo/server.js

@@ -43,7 +43,7 @@ function startServer() {
     env['COLORTERM'] = 'truecolor';
     var cols = parseInt(req.query.cols),
       rows = parseInt(req.query.rows),
-      term = pty.spawn(process.platform === 'win32' ? 'cmd.exe' : 'bash', [], {
+      term = pty.spawn(process.platform === 'win32' ? 'pwsh.exe' : 'bash', [], {
         name: 'xterm-256color',
         cols: cols || 80,
         rows: rows || 24,

package.json

@@ -68,6 +68,7 @@
     "cross-env": "^7.0.3",
     "deep-equal": "^2.0.5",
     "eslint": "^8.1.0",
+    "eslint-plugin-jsdoc": "^39.3.6",
     "express": "^4.17.1",
     "express-ws": "^5.0.2",
     "glob": "^7.2.0",

src/browser/Clipboard.ts

@@ -39,8 +39,6 @@ export function copyHandler(ev: ClipboardEvent, selectionService: ISelectionServ
 
 /**
  * Redirect the clipboard's data to the terminal's input handler.
- * @param ev The original paste event to be handled
- * @param term The terminal on which to apply the handled paste event
  */
 export function handlePasteEvent(ev: ClipboardEvent, textarea: HTMLTextAreaElement, coreService: ICoreService): void {
   ev.stopPropagation();
@@ -81,10 +79,6 @@ export function moveTextAreaUnderMouseCursor(ev: MouseEvent, textarea: HTMLTextA
 
 /**
  * Bind to right-click event and allow right-click copy and paste.
- * @param ev The original right click event to be handled.
- * @param textarea The terminal's textarea.
- * @param selectionService The terminal's selection manager.
- * @param shouldSelectWord If true and there is no selection the current word will be selected
  */
 export function rightClickHandler(ev: MouseEvent, textarea: HTMLTextAreaElement, screenElement: HTMLElement, selectionService: ISelectionService, shouldSelectWord: boolean): void {
   moveTextAreaUnderMouseCursor(ev, textarea, screenElement);

src/browser/Lifecycle.ts

@@ -7,8 +7,11 @@ import { IDisposable } from 'common/Types';
 
 /**
  * Adds a disposable listener to a node in the DOM, returning the disposable.
+ * @param node The node to add a listener to.
  * @param type The event type.
  * @param handler The handler for the listener.
+ * @param options The boolean or options object to pass on to the event
+ * listener.
  */
 export function addDisposableDomListener(
   node: Element | Window | Document,

src/browser/Terminal.ts

@@ -979,10 +979,9 @@ export class Terminal extends CoreTerminal implements ITerminal {
   }
 
   /**
-   * Handle a keydown event
-   * Key Resources:
-   *   - https://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent
-   * @param ev The keydown event to be handled.
+   * Handle a keydown [KeyboardEvent].
+   *
+   * [KeyboardEvent]: https://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent
    */
   protected _keyDown(event: KeyboardEvent): boolean | undefined {
     this._keyDownHandled = false;

src/browser/input/Mouse.ts

@@ -18,15 +18,19 @@ export function getCoordsRelativeToElement(window: Pick<Window, 'getComputedStyl
  * Gets coordinates within the terminal for a particular mouse event. The result
  * is returned as an array in the form [x, y] instead of an object as it's a
  * little faster and this function is used in some low level code.
+ * @param window The window object the element belongs to.
  * @param event The mouse event.
  * @param element The terminal's container element.
  * @param colCount The number of columns in the terminal.
  * @param rowCount The number of rows n the terminal.
+ * @param hasValidCharSize Whether there is a valid character size available.
+ * @param actualCellWidth The cell width device pixel render dimensions.
+ * @param actualCellHeight The cell height device pixel render dimensions.
  * @param isSelection Whether the request is for the selection or not. This will
  * apply an offset to the x value such that the left half of the cell will
  * select that cell and the right half will select the next cell.
  */
-export function getCoords(window: Pick<Window, 'getComputedStyle'>, event: {clientX: number, clientY: number}, element: HTMLElement, colCount: number, rowCount: number, hasValidCharSize: boolean, actualCellWidth: number, actualCellHeight: number, isSelection?: boolean): [number, number] | undefined {
+export function getCoords(window: Pick<Window, 'getComputedStyle'>, event: Pick<MouseEvent, 'clientX' | 'clientY'>, element: HTMLElement, colCount: number, rowCount: number, hasValidCharSize: boolean, actualCellWidth: number, actualCellHeight: number, isSelection?: boolean): [number, number] | undefined {
   // Coordinates cannot be measured if there are no valid
   if (!hasValidCharSize) {
     return undefined;

src/browser/input/MoveToCell.ts

@@ -68,7 +68,7 @@ function resetStartingRow(startX: number, startY: number, targetX: number, targe
   }
   return repeat(bufferLine(
     startX, startY, startX,
-    startY - wrappedRowsForRow(bufferService, startY), false, bufferService
+    startY - wrappedRowsForRow(startY, bufferService), false, bufferService
   ).length, sequence(Direction.LEFT, applicationCursor));
 }
 
@@ -77,8 +77,8 @@ function resetStartingRow(startX: number, startY: number, targetX: number, targe
  * ignoring wrapped rows
  */
 function moveToRequestedRow(startY: number, targetY: number, bufferService: IBufferService, applicationCursor: boolean): string {
-  const startRow = startY - wrappedRowsForRow(bufferService, startY);
-  const endRow = targetY - wrappedRowsForRow(bufferService, targetY);
+  const startRow = startY - wrappedRowsForRow(startY, bufferService);
+  const endRow = targetY - wrappedRowsForRow(targetY, bufferService);
 
   const rowsToMove = Math.abs(startRow - endRow) - wrappedRowsCount(startY, targetY, bufferService);
 
@@ -91,7 +91,7 @@ function moveToRequestedRow(startY: number, targetY: number, bufferService: IBuf
 function moveToRequestedCol(startX: number, startY: number, targetX: number, targetY: number, bufferService: IBufferService, applicationCursor: boolean): string {
   let startRow;
   if (moveToRequestedRow(startY, targetY, bufferService, applicationCursor).length > 0) {
-    startRow = targetY - wrappedRowsForRow(bufferService, targetY);
+    startRow = targetY - wrappedRowsForRow(targetY, bufferService);
   } else {
     startRow = startY;
   }
@@ -115,8 +115,8 @@ function moveToRequestedCol(startX: number, startY: number, targetX: number, tar
  */
 function wrappedRowsCount(startY: number, targetY: number, bufferService: IBufferService): number {
   let wrappedRows = 0;
-  const startRow = startY - wrappedRowsForRow(bufferService, startY);
-  const endRow = targetY - wrappedRowsForRow(bufferService, targetY);
+  const startRow = startY - wrappedRowsForRow(startY, bufferService);
+  const endRow = targetY - wrappedRowsForRow(targetY, bufferService);
 
   for (let i = 0; i < Math.abs(startRow - endRow); i++) {
     const direction = verticalDirection(startY, targetY) === Direction.UP ? -1 : 1;
@@ -133,7 +133,7 @@ function wrappedRowsCount(startY: number, targetY: number, bufferService: IBuffe
  * Calculates the number of wrapped rows that make up a given row.
  * @param currentRow The row to determine how many wrapped rows make it up
  */
-function wrappedRowsForRow(bufferService: IBufferService, currentRow: number): number {
+function wrappedRowsForRow(currentRow: number, bufferService: IBufferService): number {
   let rowCount = 0;
   let line = bufferService.buffer.lines.get(currentRow);
   let lineWraps = line?.isWrapped;
@@ -157,7 +157,7 @@ function wrappedRowsForRow(bufferService: IBufferService, currentRow: number): n
 function horizontalDirection(startX: number, startY: number, targetX: number, targetY: number, bufferService: IBufferService, applicationCursor: boolean): Direction {
   let startRow;
   if (moveToRequestedRow(targetX, targetY, bufferService, applicationCursor).length > 0) {
-    startRow = targetY - wrappedRowsForRow(bufferService, targetY);
+    startRow = targetY - wrappedRowsForRow(targetY, bufferService);
   } else {
     startRow = startY;
   }
@@ -237,7 +237,7 @@ function sequence(direction: Direction, applicationCursor: boolean): string {
  * Returns a string repeated a given number of times
  * Polyfill from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat
  * @param count The number of times to repeat the string
- * @param string The string that is to be repeated
+ * @param str The string that is to be repeated
  */
 function repeat(count: number, str: string): string {
   count = Math.floor(count);

src/browser/services/SelectionService.ts

@@ -757,19 +757,20 @@ export class SelectionService extends Disposable implements ISelectionService {
   }
 
   /**
-   * Converts a viewport column to the character index on the buffer line, the
-   * latter takes into account wide characters.
-   * @param coords The coordinates to find the 2 index for.
+   * Converts a viewport column (0 to cols - 1) to the character index on the
+   * buffer line, the latter takes into account wide and null characters.
+   * @param bufferLine The buffer line to use.
+   * @param x The x index in the buffer line to convert.
    */
-  private _convertViewportColToCharacterIndex(bufferLine: IBufferLine, coords: [number, number]): number {
-    let charIndex = coords[0];
-    for (let i = 0; coords[0] >= i; i++) {
+  private _convertViewportColToCharacterIndex(bufferLine: IBufferLine, x: number): number {
+    let charIndex = x;
+    for (let i = 0; x >= i; i++) {
       const length = bufferLine.loadCell(i, this._workCell).getChars().length;
       if (this._workCell.getWidth() === 0) {
         // Wide characters aren't included in the line string so decrement the
         // index so the index is back on the wide character.
         charIndex--;
-      } else if (length > 1 && coords[0] !== i) {
+      } else if (length > 1 && x !== i) {
         // Emojis take up multiple characters, so adjust accordingly. For these
         // we don't want ot include the character at the column as we're
         // returning the start index in the string, not the end index.
@@ -816,7 +817,7 @@ export class SelectionService extends Disposable implements ISelectionService {
     const line = buffer.translateBufferLineToString(coords[1], false);
 
     // Get actual index, taking into consideration wide characters
-    let startIndex = this._convertViewportColToCharacterIndex(bufferLine, coords);
+    let startIndex = this._convertViewportColToCharacterIndex(bufferLine, coords[0]);
     let endIndex = startIndex;
 
     // Record offset to be used later
@@ -1000,7 +1001,7 @@ export class SelectionService extends Disposable implements ISelectionService {
   /**
    * Gets whether the character is considered a word separator by the select
    * word logic.
-   * @param char The character to check.
+   * @param cell The cell to check.
    */
   private _isCharWordSeparator(cell: CellData): boolean {
     // Zero width characters are never separators as they are always to the

src/common/CoreTerminal.ts

@@ -184,6 +184,7 @@ export abstract class CoreTerminal extends Disposable implements ICoreTerminal {
 
   /**
    * Scroll the terminal down 1 row, creating a blank line.
+   * @param eraseAttr The attribute data to use the for blank line.
    * @param isWrapped Whether the new line is wrapped from the previous line.
    */
   public scroll(eraseAttr: IAttributeData, isWrapped: boolean = false): void {

src/common/InputHandler.ts

@@ -11,7 +11,7 @@ import { EscapeSequenceParser } from 'common/parser/EscapeSequenceParser';
 import { Disposable } from 'common/Lifecycle';
 import { StringToUtf32, stringFromCodePoint, Utf8ToUtf32 } from 'common/input/TextDecoder';
 import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
-import { EventEmitter, IEvent } from 'common/EventEmitter';
+import { EventEmitter } from 'common/EventEmitter';
 import { IParsingState, IEscapeSequenceParser, IParams, IFunctionIdentifier } from 'common/parser/Types';
 import { NULL_CELL_CODE, NULL_CELL_WIDTH, Attributes, FgFlags, BgFlags, Content, UnderlineStyle } from 'common/buffer/Constants';
 import { CellData } from 'common/buffer/CellData';
@@ -1116,10 +1116,11 @@ export class InputHandler extends Disposable implements IInputHandler {
   /**
    * Helper method to erase cells in a terminal row.
    * The cell gets replaced with the eraseChar of the terminal.
-   * @param y row index
-   * @param start first cell index to be erased
-   * @param end   end - 1 is last erased cell
-   * @param cleanWrap clear the isWrapped flag
+   * @param y The row index relative to the viewport.
+   * @param start The start x index of the range to be erased.
+   * @param end The end x index of the range to be erased (exclusive).
+   * @param clearWrap clear the isWrapped flag
+   * @param respectProtect Whether to respect the protection attribute (DECSCA).
    */
   private _eraseInBufferLine(y: number, start: number, end: number, clearWrap: boolean = false, respectProtect: boolean = false): void {
     const line = this._activeBuffer.lines.get(this._activeBuffer.ybase + y)!;

src/common/buffer/Buffer.ts

@@ -486,7 +486,7 @@ export class Buffer implements IBuffer {
    * TODO: respect trim flag after fixing #1685
    * @param lineIndex line index the string was retrieved from
    * @param stringIndex index within the string
-   * @param startCol column offset the string was retrieved from
+   * @param trimRight Whether to trim whitespace to the right.
    */
   public stringIndexToBufferIndex(lineIndex: number, stringIndex: number, trimRight: boolean = false): BufferIndex {
     while (stringIndex) {
@@ -515,7 +515,7 @@ export class Buffer implements IBuffer {
    * Wide characters will count as two columns in the resulting string. This
    * function is useful for getting the actual text underneath the raw selection
    * position.
-   * @param line The line being translated.
+   * @param lineIndex The absolute index of the line being translated.
    * @param trimRight Whether to trim whitespace to the right.
    * @param startCol The column to start at.
    * @param endCol The column to end at.

src/common/buffer/BufferReflow.ts

@@ -16,7 +16,10 @@ export interface INewLayoutResult {
  * Evaluates and returns indexes to be removed after a reflow larger occurs. Lines will be removed
  * when a wrapped line unwraps.
  * @param lines The buffer lines.
+ * @param oldCols The columns before resize
  * @param newCols The columns after resize.
+ * @param bufferAbsoluteY The absolute y position of the cursor (baseY + cursorY).
+ * @param nullCell The cell data to use when filling in empty cells.
  */
 export function reflowLargerGetLinesToRemove(lines: CircularList<IBufferLine>, oldCols: number, newCols: number, bufferAbsoluteY: number, nullCell: ICellData): number[] {
   // Gather all BufferLines that need to be removed from the Buffer here so that they can be

src/common/buffer/BufferSet.ts

@@ -24,7 +24,6 @@ export class BufferSet extends Disposable implements IBufferSet {
 
   /**
    * Create a new BufferSet for the given terminal.
-   * @param _terminal - The terminal the BufferSet will belong to
    */
   constructor(
     private readonly _optionsService: IOptionsService,

src/common/services/BufferService.ts

@@ -54,6 +54,7 @@ export class BufferService extends Disposable implements IBufferService {
 
   /**
    * Scroll the terminal down 1 row, creating a blank line.
+   * @param eraseAttr The attribute data to use the for blank line.
    * @param isWrapped Whether the new line is wrapped from the previous line.
    */
   public scroll(eraseAttr: IAttributeData, isWrapped: boolean = false): void {