Merge pull request #4206 from Tyriar/eslint-jsdoc

Add eslint-plugin-jsdoc with minimal comment rules

.eslintrc.json

@@ -39,7 +39,8 @@
     "**/*.js"
   ],
   "plugins": [
-    "@typescript-eslint"
+    "@typescript-eslint",
+    "jsdoc"
   ],
   "rules": {
     "no-extra-semi": "error",
@@ -141,6 +142,9 @@
       "warn",
       "always"
     ],
+    "jsdoc/check-alignment": 1,
+    "jsdoc/check-param-names": 1,
+    "jsdoc/no-multi-asterisks": 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';
@@ -162,11 +162,11 @@ export abstract class BaseRenderLayer extends Disposable implements IRenderLayer
   }
 
   /**
-     * Fills a 1px line (2px on HDPI) at the middle of the cell. This uses the
-     * existing fillStyle on the context.
-     * @param x The column to fill.
-     * @param y The row to fill.
-     */
+   * Fills a 1px line (2px on HDPI) at the middle of the cell. This uses the
+   * existing fillStyle on the context.
+   * @param x The column to fill.
+   * @param y The row to fill.
+   */
   protected _fillMiddleLineAtCells(x: number, y: number, width: number = 1): void {
     const cellOffset = Math.ceil(this._scaledCellHeight * 0.5);
     this._ctx.fillRect(
@@ -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-canvas/src/Types.d.ts

@@ -64,7 +64,7 @@ export interface IRenderLayer extends IDisposable {
   handleBlur(): void;
 
   /**
-   * * Called when the terminal gets focus.
+   * Called when the terminal gets focus.
    */
   handleFocus(): void;
 

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

@@ -126,7 +126,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
    * doesn't exist, do nothing.
    * @param term The search term.
    * @param searchOptions Search options.
-   * @return Whether a result was found.
+   * @returns Whether a result was found.
    */
   public findNext(term: string, searchOptions?: ISearchOptions): boolean {
     if (!this._terminal) {
@@ -307,7 +307,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
    * doesn't exist, do nothing.
    * @param term The search term.
    * @param searchOptions Search options.
-   * @return Whether a result was found.
+   * @returns Whether a result was found.
    */
   public findPrevious(term: string, searchOptions?: ISearchOptions): boolean {
     if (!this._terminal) {
@@ -477,10 +477,10 @@ 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.
+   * @returns The search result if it was found.
    */
   protected _findInLine(term: string, searchPosition: ISearchPosition, searchOptions: ISearchOptions = {}, isReverseSearch: boolean = false): ISearchResult | undefined {
     const terminal = this._terminal!;
@@ -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 {
@@ -662,7 +662,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon {
   /**
    * Selects and scrolls to a result.
    * @param result The result to select.
-   * @return Whether a result was selected.
+   * @returns Whether a result was selected.
    */
   private _selectResult(result: ISearchResult | undefined, options?: ISearchDecorationOptions, noScroll?: boolean): boolean {
     const terminal = this._terminal!;
@@ -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);

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

@@ -13,7 +13,7 @@ export interface IRenderLayer extends IDisposable {
   handleBlur(terminal: Terminal): void;
 
   /**
-   * * Called when the terminal gets focus.
+   * Called when the terminal gets focus.
    */
   handleFocus(terminal: Terminal): void;
 

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/CompositionHelper.ts

@@ -89,7 +89,7 @@ export class CompositionHelper {
   /**
    * Handles the keydown event, routing any necessary events to the CompositionHelper functions.
    * @param ev The keydown event.
-   * @return Whether the Terminal should continue processing the keydown event.
+   * @returns Whether the Terminal should continue processing the keydown event.
    */
   public keydown(ev: KeyboardEvent): boolean {
     if (this._isComposing || this._isSendingComposition) {

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/selection/SelectionModel.ts

@@ -118,7 +118,7 @@ export class SelectionModel {
   /**
    * Handle the buffer being trimmed, adjust the selection position.
    * @param amount The amount the buffer is being trimmed.
-   * @return Whether a refresh is necessary.
+   * @returns Whether a refresh is necessary.
    */
   public handleTrim(amount: number): boolean {
     // Adjust the selection position based on the trimmed amount.

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/CircularList.ts

@@ -82,7 +82,7 @@ export class CircularList<T> extends Disposable implements ICircularList<T> {
    * Note that for performance reasons there is no bounds checking here, the index reference is
    * circular so this should always return a value and never throw.
    * @param index The index of the value to get.
-   * @return The value corresponding to the index.
+   * @returns The value corresponding to the index.
    */
   public get(index: number): T | undefined {
     return this._array[this._getCyclicIndex(index)];
@@ -138,7 +138,7 @@ export class CircularList<T> extends Disposable implements ICircularList<T> {
 
   /**
    * Removes and returns the last value on the list.
-   * @return The popped value.
+   * @returns The popped value.
    */
   public pop(): T | undefined {
     return this._array[this._getCyclicIndex(this._length-- - 1)];

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 {