typings: add JSDoc typings for readline

Added JSDoc typings for the `readline` lib module. PR-URL: #38253 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>
nodejs · May 17, 2021 · c0f0c9a · c0f0c9a
1 parent e59131d
commit c0f0c9a
Showing 1 changed file with 84 additions and 8 deletions.
diff --git a/lib/readline.js b/lib/readline.js
@@ -107,6 +107,11 @@ const { StringDecoder } = require('string_decoder');
 // Lazy load Readable for startup performance.
 let Readable;
 
+/**
+ * @typedef {import('./stream.js').Readable} Readable
+ * @typedef {import('./stream.js').Writable} Writable
+ */
+
 const kHistorySize = 30;
 const kMincrlfDelay = 100;
 // \r\n, \n, or \r followed by something other than \n
@@ -118,6 +123,27 @@ const kQuestionCancel = Symbol('kQuestionCancel');
 // GNU readline library - keyseq-timeout is 500ms (default)
 const ESCAPE_CODE_TIMEOUT = 500;
 
+/**
+ * Creates a new `readline.Interface` instance.
+ * @param {Readable | {
+ *   input: Readable;
+ *   output: Writable;
+ *   completer?: Function;
+ *   terminal?: boolean;
+ *   history?: string[];
+ *   historySize?: number;
+ *   removeHistoryDuplicates?: boolean;
+ *   prompt?: string;
+ *   crlfDelay?: number;
+ *   escapeCodeTimeout?: number;
+ *   tabSize?: number;
+ *   signal?: AbortSignal;
+ *   }} input
+ * @param {Writable} [output]
+ * @param {Function} [completer]
+ * @param {boolean} [terminal]
+ * @returns {Interface}
+ */
 function createInterface(input, output, completer, terminal) {
   return new Interface(input, output, completer, terminal);
 }
@@ -348,11 +374,19 @@ ObjectDefineProperty(Interface.prototype, 'columns', {
   }
 });
 
+/**
+ * Sets the prompt written to the output.
+ * @param {string} prompt
+ * @returns {void}
+ */
 Interface.prototype.setPrompt = function(prompt) {
   this._prompt = prompt;
 };
 
-
+/**
+ * Returns the current prompt used by `rl.prompt()`.
+ * @returns {string}
+ */
 Interface.prototype.getPrompt = function() {
   return this._prompt;
 };
@@ -368,7 +402,11 @@ Interface.prototype._setRawMode = function(mode) {
   return wasInRawMode;
 };
 
-
+/**
+ * Writes the configured `prompt` to a new line in `output`.
+ * @param {boolean} [preserveCursor]
+ * @returns {void}
+ */
 Interface.prototype.prompt = function(preserveCursor) {
   if (this.paused) this.resume();
   if (this.terminal && process.env.TERM !== 'dumb') {
@@ -379,7 +417,13 @@ Interface.prototype.prompt = function(preserveCursor) {
   }
 };
 
-
+/**
+ * Displays `query` by writing it to the `output`.
+ * @param {string} query
+ * @param {{ signal?: AbortSignal; }} [options]
+ * @param {Function} cb
+ * @returns {void}
+ */
 Interface.prototype.question = function(query, options, cb) {
   cb = typeof options === 'function' ? options : cb;
   options = typeof options === 'object' && options !== null ? options : {};
@@ -528,7 +572,10 @@ Interface.prototype._refreshLine = function() {
   this.prevRows = cursorPos.rows;
 };
 
-
+/**
+ * Closes the `readline.Interface` instance.
+ * @returns {void}
+ */
 Interface.prototype.close = function() {
   if (this.closed) return;
   this.pause();
@@ -539,7 +586,10 @@ Interface.prototype.close = function() {
   this.emit('close');
 };
 
-
+/**
+ * Pauses the `input` stream.
+ * @returns {void | Interface}
+ */
 Interface.prototype.pause = function() {
   if (this.paused) return;
   this.input.pause();
@@ -548,7 +598,10 @@ Interface.prototype.pause = function() {
   return this;
 };
 
-
+/**
+ * Resumes the `input` stream if paused.
+ * @returns {void | Interface}
+ */
 Interface.prototype.resume = function() {
   if (!this.paused) return;
   this.input.resume();
@@ -557,7 +610,18 @@ Interface.prototype.resume = function() {
   return this;
 };
 
-
+/**
+ * Writes either `data` or a `key` sequence identified by
+ * `key` to the `output`.
+ * @param {string} d
+ * @param {{
+ *   ctrl?: boolean;
+ *   meta?: boolean;
+ *   shift?: boolean;
+ *   name?: string;
+ *   }} [key]
+ * @returns {void}
+ */
 Interface.prototype.write = function(d, key) {
   if (this.paused) this.resume();
   if (this.terminal) {
@@ -868,7 +932,14 @@ Interface.prototype._getDisplayPos = function(str) {
   return { cols, rows };
 };
 
-// Returns current cursor's position and line
+/**
+ * Returns the real position of the cursor in relation
+ * to the input prompt + string.
+ * @returns {{
+ *   rows: number;
+ *   cols: number;
+ *   }}
+ */
 Interface.prototype.getCursorPos = function() {
   const strBeforeCursor = this._prompt +
                           StringPrototypeSlice(this.line, 0, this.cursor);
@@ -1197,6 +1268,11 @@ Interface.prototype._ttyWrite = function(s, key) {
   }
 };
 
+/**
+ * Creates an `AsyncIterator` object that iterates through
+ * each line in the input stream as a string.
+ * @returns {Symbol.AsyncIterator}
+ */
 Interface.prototype[SymbolAsyncIterator] = function() {
   if (this[kLineObjectStream] === undefined) {
     if (Readable === undefined) {