From 114924f3fa60d9a05c5a6e4337ceccd41c817330 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Sat, 15 Oct 2022 08:38:14 -0700 Subject: [PATCH 1/4] Add eslint-plugin-jsdoc and enable check-param-names --- .eslintrc.json | 4 +- .../xterm-addon-canvas/src/BaseRenderLayer.ts | 3 +- addons/xterm-addon-search/src/SearchAddon.ts | 12 ++-- .../src/WebLinkProvider.ts | 3 +- addons/xterm-addon-webgl/src/WebglRenderer.ts | 2 - .../src/renderLayer/BaseRenderLayer.ts | 1 - demo/server.js | 2 +- package.json | 1 + src/browser/Clipboard.ts | 6 -- src/browser/Lifecycle.ts | 3 + src/browser/Terminal.ts | 7 +- src/browser/input/Mouse.ts | 6 +- src/browser/input/MoveToCell.ts | 18 +++--- src/browser/services/SelectionService.ts | 19 +++--- src/common/CoreTerminal.ts | 1 + src/common/InputHandler.ts | 11 ++-- src/common/buffer/Buffer.ts | 4 +- src/common/buffer/BufferReflow.ts | 3 + src/common/buffer/BufferSet.ts | 1 - src/common/services/BufferService.ts | 1 + yarn.lock | 64 +++++++++++++++++++ 21 files changed, 120 insertions(+), 52 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index e6db42e2..8064820e 100644 --- a/.eslintrc.json +++ b/.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", diff --git a/addons/xterm-addon-canvas/src/BaseRenderLayer.ts b/addons/xterm-addon-canvas/src/BaseRenderLayer.ts index 8f203400..872d8cfc 100644 --- a/addons/xterm-addon-canvas/src/BaseRenderLayer.ts +++ b/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); diff --git a/addons/xterm-addon-search/src/SearchAddon.ts b/addons/xterm-addon-search/src/SearchAddon.ts index 249dd594..f76d28c2 100644 --- a/addons/xterm-addon-search/src/SearchAddon.ts +++ b/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 { diff --git a/addons/xterm-addon-web-links/src/WebLinkProvider.ts b/addons/xterm-addon-web-links/src/WebLinkProvider.ts index 8e9a8408..2f2ccddf 100644 --- a/addons/xterm-addon-web-links/src/WebLinkProvider.ts +++ b/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 = ''; diff --git a/addons/xterm-addon-webgl/src/WebglRenderer.ts b/addons/xterm-addon-webgl/src/WebglRenderer.ts index fddeb99c..ded9130a 100644 --- a/addons/xterm-addon-webgl/src/WebglRenderer.ts +++ b/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) { diff --git a/addons/xterm-addon-webgl/src/renderLayer/BaseRenderLayer.ts b/addons/xterm-addon-webgl/src/renderLayer/BaseRenderLayer.ts index 8ed12d86..aa08b583 100644 --- a/addons/xterm-addon-webgl/src/renderLayer/BaseRenderLayer.ts +++ b/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); diff --git a/demo/server.js b/demo/server.js index 0e82f9e9..a152a8b8 100644 --- a/demo/server.js +++ b/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, diff --git a/package.json b/package.json index a36ad5c9..d8f1141b 100644 --- a/package.json +++ b/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", diff --git a/src/browser/Clipboard.ts b/src/browser/Clipboard.ts index 29e865c8..1f9ea9ec 100644 --- a/src/browser/Clipboard.ts +++ b/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); diff --git a/src/browser/Lifecycle.ts b/src/browser/Lifecycle.ts index 6e841794..8e0272b2 100644 --- a/src/browser/Lifecycle.ts +++ b/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, diff --git a/src/browser/Terminal.ts b/src/browser/Terminal.ts index 9056cbe3..b5262b1e 100644 --- a/src/browser/Terminal.ts +++ b/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; diff --git a/src/browser/input/Mouse.ts b/src/browser/input/Mouse.ts index c34e8370..309d9265 100644 --- a/src/browser/input/Mouse.ts +++ b/src/browser/input/Mouse.ts @@ -18,15 +18,19 @@ export function getCoordsRelativeToElement(window: Pick, 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, event: Pick, 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; diff --git a/src/browser/input/MoveToCell.ts b/src/browser/input/MoveToCell.ts index 82e767cd..c88db7b2 100644 --- a/src/browser/input/MoveToCell.ts +++ b/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); diff --git a/src/browser/services/SelectionService.ts b/src/browser/services/SelectionService.ts index 868fadda..763f938b 100644 --- a/src/browser/services/SelectionService.ts +++ b/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 diff --git a/src/common/CoreTerminal.ts b/src/common/CoreTerminal.ts index f4a7d301..c5182554 100644 --- a/src/common/CoreTerminal.ts +++ b/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 { diff --git a/src/common/InputHandler.ts b/src/common/InputHandler.ts index b91b446c..95ec00c1 100644 --- a/src/common/InputHandler.ts +++ b/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)!; diff --git a/src/common/buffer/Buffer.ts b/src/common/buffer/Buffer.ts index c8b0d1b2..7bee6dfd 100644 --- a/src/common/buffer/Buffer.ts +++ b/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. diff --git a/src/common/buffer/BufferReflow.ts b/src/common/buffer/BufferReflow.ts index ece9a96e..af1c6473 100644 --- a/src/common/buffer/BufferReflow.ts +++ b/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, 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 diff --git a/src/common/buffer/BufferSet.ts b/src/common/buffer/BufferSet.ts index bc7aa58e..da902aff 100644 --- a/src/common/buffer/BufferSet.ts +++ b/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, diff --git a/src/common/services/BufferService.ts b/src/common/services/BufferService.ts index 3f15f242..528d2674 100644 --- a/src/common/services/BufferService.ts +++ b/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 { diff --git a/yarn.lock b/yarn.lock index 315dddab..8e2dd19d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -189,6 +189,15 @@ resolved "https://registry.yarnpkg.com/@discoveryjs/json-ext/-/json-ext-0.5.5.tgz#9283c9ce5b289a3c4f61c12757469e59377f81f3" integrity sha512-6nFkfkmSeV/rqSaS4oWHgmpnYw194f6hmWF5is6b0J1naJZoiD0NTc9AiUwPHvWsowkjuHErCZT1wa0jg+BLIA== +"@es-joy/jsdoccomment@~0.31.0": + version "0.31.0" + resolved "https://registry.yarnpkg.com/@es-joy/jsdoccomment/-/jsdoccomment-0.31.0.tgz#dbc342cc38eb6878c12727985e693eaef34302bc" + integrity sha512-tc1/iuQcnaiSIUVad72PBierDFpsxdUHtEF/OrfqvM1CBAsIoMP51j52jTMb3dXriwhieTo289InzZj72jL3EQ== + dependencies: + comment-parser "1.3.1" + esquery "^1.4.0" + jsdoc-type-pratt-parser "~3.1.0" + "@eslint/eslintrc@^1.0.3": version "1.0.3" resolved "https://registry.yarnpkg.com/@eslint/eslintrc/-/eslintrc-1.0.3.tgz#41f08c597025605f672251dcc4e8be66b5ed7366" @@ -1278,6 +1287,11 @@ commander@^7.0.0: resolved "https://registry.yarnpkg.com/commander/-/commander-7.2.0.tgz#a36cb57d0b501ce108e4d20559a150a391d97ab7" integrity sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw== +comment-parser@1.3.1: + version "1.3.1" + resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.3.1.tgz#3d7ea3adaf9345594aedee6563f422348f165c1b" + integrity sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA== + commondir@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/commondir/-/commondir-1.0.1.tgz#ddd800da0c66127393cca5950ea968a3aaf1253b" @@ -1392,6 +1406,13 @@ debug@^4.3.2: dependencies: ms "2.1.2" +debug@^4.3.4: + version "4.3.4" + resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.4.tgz#1319f6579357f2338d3337d2cdd4914bb5dcc865" + integrity sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ== + dependencies: + ms "2.1.2" + decamelize@^1.2.0: version "1.2.0" resolved "https://registry.yarnpkg.com/decamelize/-/decamelize-1.2.0.tgz#f6534d15148269b20352e7bee26f501f9a191290" @@ -1647,6 +1668,19 @@ escodegen@^2.0.0: optionalDependencies: source-map "~0.6.1" +eslint-plugin-jsdoc@^39.3.6: + version "39.3.6" + resolved "https://registry.yarnpkg.com/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.3.6.tgz#6ba29f32368d72a51335a3dc9ccd22ad0437665d" + integrity sha512-R6dZ4t83qPdMhIOGr7g2QII2pwCjYyKP+z0tPOfO1bbAbQyKC20Y2Rd6z1te86Lq3T7uM8bNo+VD9YFpE8HU/g== + dependencies: + "@es-joy/jsdoccomment" "~0.31.0" + comment-parser "1.3.1" + debug "^4.3.4" + escape-string-regexp "^4.0.0" + esquery "^1.4.0" + semver "^7.3.7" + spdx-expression-parse "^3.0.1" + eslint-scope@5.1.1, eslint-scope@^5.1.1: version "5.1.1" resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-5.1.1.tgz#e786e59a66cb92b3f6c1fb0d508aab174848f48c" @@ -2597,6 +2631,11 @@ js-yaml@^3.13.1: argparse "^1.0.7" esprima "^4.0.0" +jsdoc-type-pratt-parser@~3.1.0: + version "3.1.0" + resolved "https://registry.yarnpkg.com/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.1.0.tgz#a4a56bdc6e82e5865ffd9febc5b1a227ff28e67e" + integrity sha512-MgtD0ZiCDk9B+eI73BextfRrVQl0oyzRG8B2BjORts6jbunj4ScKPcyXGTbB6eXL4y9TzxCm6hyeLq/2ASzNdw== + jsdom@^18.0.1: version "18.0.1" resolved "https://registry.yarnpkg.com/jsdom/-/jsdom-18.0.1.tgz#7317c91be425f31ff25814ad427eed8a2a310b61" @@ -3434,6 +3473,13 @@ semver@^7.2.1, semver@^7.3.4, semver@^7.3.5: dependencies: lru-cache "^6.0.0" +semver@^7.3.7: + version "7.3.8" + resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.8.tgz#07a78feafb3f7b32347d725e33de7e2a2df67798" + integrity sha512-NB1ctGL5rlHrPJtFDVIVzTyQylMLu9N9VICA6HSFJo8MCGVTMW6gfpicwKmmK/dAjTOrqu5l63JJOpDSrAis3A== + dependencies: + lru-cache "^6.0.0" + send@0.17.1: version "0.17.1" resolved "https://registry.yarnpkg.com/send/-/send-0.17.1.tgz#c1d8b059f7900f7466dd4938bdc44e11ddb376c8" @@ -3579,6 +3625,24 @@ spawn-wrap@^2.0.0: signal-exit "^3.0.2" which "^2.0.1" +spdx-exceptions@^2.1.0: + version "2.3.0" + resolved "https://registry.yarnpkg.com/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz#3f28ce1a77a00372683eade4a433183527a2163d" + integrity sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A== + +spdx-expression-parse@^3.0.1: + version "3.0.1" + resolved "https://registry.yarnpkg.com/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz#cf70f50482eefdc98e3ce0a6833e4a53ceeba679" + integrity sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q== + dependencies: + spdx-exceptions "^2.1.0" + spdx-license-ids "^3.0.0" + +spdx-license-ids@^3.0.0: + version "3.0.12" + resolved "https://registry.yarnpkg.com/spdx-license-ids/-/spdx-license-ids-3.0.12.tgz#69077835abe2710b65f03969898b6637b505a779" + integrity sha512-rr+VVSXtRhO4OHbXUiAF7xW3Bo9DuuF6C5jH+q/x15j2jniycgKbxU09Hr0WqlSLUs4i4ltHGXqTe7VHclYWyA== + sprintf-js@~1.0.2: version "1.0.3" resolved "https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c" From 49e0480f785151760b07efa7c22d388a515b1258 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Sat, 15 Oct 2022 08:39:32 -0700 Subject: [PATCH 2/4] Add rule jsdoc/check-alignment --- .eslintrc.json | 1 + addons/xterm-addon-canvas/src/BaseRenderLayer.ts | 10 +++++----- src/common/parser/Constants.ts | 4 ++-- src/common/parser/Types.d.ts | 4 ++-- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index 8064820e..58082186 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -142,6 +142,7 @@ "warn", "always" ], + "jsdoc/check-alignment": 1, "jsdoc/check-param-names": 1, "keyword-spacing": "warn", "new-parens": "warn", diff --git a/addons/xterm-addon-canvas/src/BaseRenderLayer.ts b/addons/xterm-addon-canvas/src/BaseRenderLayer.ts index 872d8cfc..29c85558 100644 --- a/addons/xterm-addon-canvas/src/BaseRenderLayer.ts +++ b/addons/xterm-addon-canvas/src/BaseRenderLayer.ts @@ -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( diff --git a/src/common/parser/Constants.ts b/src/common/parser/Constants.ts index 85156c3e..7fe24f34 100644 --- a/src/common/parser/Constants.ts +++ b/src/common/parser/Constants.ts @@ -24,8 +24,8 @@ export const enum ParserState { } /** -* Internal actions of EscapeSequenceParser. -*/ + * Internal actions of EscapeSequenceParser. + */ export const enum ParserAction { IGNORE = 0, ERROR = 1, diff --git a/src/common/parser/Types.d.ts b/src/common/parser/Types.d.ts index 3a621eab..a1ea0ec2 100644 --- a/src/common/parser/Types.d.ts +++ b/src/common/parser/Types.d.ts @@ -142,8 +142,8 @@ export type PrintFallbackHandlerType = PrintHandlerType; /** -* EscapeSequenceParser interface. -*/ + * EscapeSequenceParser interface. + */ export interface IEscapeSequenceParser extends IDisposable { /** * Preceding codepoint to get REP working correctly. From 9f1a71485cfb6b62fa8faa78e4c38ecca7e4c8b3 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Sat, 15 Oct 2022 08:41:49 -0700 Subject: [PATCH 3/4] Fix invalid jsdoc tags --- addons/xterm-addon-search/src/SearchAddon.ts | 8 ++++---- src/browser/input/CompositionHelper.ts | 2 +- src/browser/selection/SelectionModel.ts | 2 +- src/common/CircularList.ts | 4 ++-- typings/xterm-headless.d.ts | 8 ++++---- typings/xterm.d.ts | 10 +++++----- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/addons/xterm-addon-search/src/SearchAddon.ts b/addons/xterm-addon-search/src/SearchAddon.ts index f76d28c2..3f71af29 100644 --- a/addons/xterm-addon-search/src/SearchAddon.ts +++ b/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) { @@ -480,7 +480,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon { * @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!; @@ -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!; diff --git a/src/browser/input/CompositionHelper.ts b/src/browser/input/CompositionHelper.ts index 39ccaa23..ba7d4b6a 100644 --- a/src/browser/input/CompositionHelper.ts +++ b/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) { diff --git a/src/browser/selection/SelectionModel.ts b/src/browser/selection/SelectionModel.ts index 041c7b24..b26cf944 100644 --- a/src/browser/selection/SelectionModel.ts +++ b/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. diff --git a/src/common/CircularList.ts b/src/common/CircularList.ts index b7e1e075..8ab80d56 100644 --- a/src/common/CircularList.ts +++ b/src/common/CircularList.ts @@ -82,7 +82,7 @@ export class CircularList extends Disposable implements ICircularList { * 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 extends Disposable implements ICircularList { /** * 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)]; diff --git a/typings/xterm-headless.d.ts b/typings/xterm-headless.d.ts index 7453b7e2..af55ffac 100644 --- a/typings/xterm-headless.d.ts +++ b/typings/xterm-headless.d.ts @@ -1080,7 +1080,7 @@ declare module 'xterm-headless' { * Return true if the sequence was handled; false if we should try * a previous handler (set by addCsiHandler or setCsiHandler). * The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean): IDisposable; @@ -1099,7 +1099,7 @@ declare module 'xterm-headless' { * Return true if the sequence was handled; false if we should try * a previous handler (set by addDcsHandler or setDcsHandler). * The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean): IDisposable; @@ -1112,7 +1112,7 @@ declare module 'xterm-headless' { * Return true if the sequence was handled; false if we should try * a previous handler (set by addEscHandler or setEscHandler). * The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerEscHandler(id: IFunctionIdentifier, handler: () => boolean): IDisposable; @@ -1130,7 +1130,7 @@ declare module 'xterm-headless' { * Return true if the sequence was handled; false if we should try * a previous handler (set by addOscHandler or setOscHandler). * The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerOscHandler(ident: number, callback: (data: string) => boolean): IDisposable; } diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index 0e2b0357..aec0fdbc 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -905,7 +905,7 @@ declare module 'xterm' { * with a string of text that is eligible for joining and returns an array * where each entry is an array containing the start (inclusive) and end * (exclusive) indexes of ranges that should be rendered as a single unit. - * @return The ID of the new joiner, this can be used to deregister + * @returns The ID of the new joiner, this can be used to deregister */ registerCharacterJoiner(handler: (text: string) => [number, number][]): number; @@ -1558,7 +1558,7 @@ declare module 'xterm' { * array will contain subarrays with their numercial values. * Return `true` if the sequence was handled, `false` if the parser should try * a previous handler. The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean | Promise): IDisposable; @@ -1576,7 +1576,7 @@ declare module 'xterm' { * The function gets the payload and numerical parameters as arguments. * Return `true` if the sequence was handled, `false` if the parser should try * a previous handler. The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean | Promise): IDisposable; @@ -1588,7 +1588,7 @@ declare module 'xterm' { * @param callback The function to handle the sequence. * Return `true` if the sequence was handled, `false` if the parser should try * a previous handler. The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerEscHandler(id: IFunctionIdentifier, handler: () => boolean | Promise): IDisposable; @@ -1605,7 +1605,7 @@ declare module 'xterm' { * The callback is called with OSC data string. * Return `true` if the sequence was handled, `false` if the parser should try * a previous handler. The most recently added handler is tried first. - * @return An IDisposable you can call to remove this handler. + * @returns An IDisposable you can call to remove this handler. */ registerOscHandler(ident: number, callback: (data: string) => boolean | Promise): IDisposable; } From 5204374494d5ff1b24191bb977cd3845be86746e Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Sat, 15 Oct 2022 08:43:06 -0700 Subject: [PATCH 4/4] Add no-multi-asterisks rule --- .eslintrc.json | 1 + addons/xterm-addon-canvas/src/Types.d.ts | 2 +- addons/xterm-addon-webgl/src/renderLayer/Types.ts | 2 +- src/common/buffer/BufferLine.ts | 2 +- src/common/buffer/CellData.ts | 2 +- 5 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index 58082186..822ee4ba 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -144,6 +144,7 @@ ], "jsdoc/check-alignment": 1, "jsdoc/check-param-names": 1, + "jsdoc/no-multi-asterisks": 1, "keyword-spacing": "warn", "new-parens": "warn", "no-duplicate-imports": "warn", diff --git a/addons/xterm-addon-canvas/src/Types.d.ts b/addons/xterm-addon-canvas/src/Types.d.ts index 753bd127..edd5c2ea 100644 --- a/addons/xterm-addon-canvas/src/Types.d.ts +++ b/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; diff --git a/addons/xterm-addon-webgl/src/renderLayer/Types.ts b/addons/xterm-addon-webgl/src/renderLayer/Types.ts index bad56091..3dbdfd9c 100644 --- a/addons/xterm-addon-webgl/src/renderLayer/Types.ts +++ b/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; diff --git a/src/common/buffer/BufferLine.ts b/src/common/buffer/BufferLine.ts index 875ac6c9..5a192203 100644 --- a/src/common/buffer/BufferLine.ts +++ b/src/common/buffer/BufferLine.ts @@ -130,7 +130,7 @@ export class BufferLine implements IBufferLine { * Test whether contains any chars. * Basically an empty has no content, but other cells might differ in FG/BG * from real empty cells. - * */ + */ public hasContent(index: number): number { return this._data[index * CELL_SIZE + Cell.CONTENT] & Content.HAS_CONTENT_MASK; } diff --git a/src/common/buffer/CellData.ts b/src/common/buffer/CellData.ts index a87b5795..9454c553 100644 --- a/src/common/buffer/CellData.ts +++ b/src/common/buffer/CellData.ts @@ -47,7 +47,7 @@ export class CellData extends AttributeData implements ICellData { * Note this returns the UTF32 codepoint of single chars, * if content is a combined string it returns the codepoint * of the last char in string to be in line with code in CharData. - * */ + */ public getCode(): number { return (this.isCombined()) ? this.combinedData.charCodeAt(this.combinedData.length - 1)