docs: replace @return with @returns (#6006)

The former is not understood by TSDoc.
puppeteer · Jun 12, 2020 · 8a099a0 · 8a099a0
1 parent 23f18d8
commit 8a099a0
Show file tree

Hide file tree

Showing 33 changed files with 98 additions and 88 deletions.
diff --git a/examples/custom-event.js b/examples/custom-event.js
@@ -30,7 +30,7 @@ const puppeteer = require('puppeteer');
   /**
    * Attach an event listener to page to capture a custom event on page load/navigation.
    * @param {string} type Event name.
-   * @return {!Promise}
+   * @returns {!Promise}
    */
   function listenFor(type) {
     return page.evaluateOnNewDocument((type) => {

diff --git a/install.js b/install.js
@@ -97,7 +97,7 @@ async function download() {
 
     /**
      * @param {!Array<string>}
-     * @return {!Promise}
+     * @returns {!Promise}
      */
     function onSuccess(localRevisions) {
       if (os.arch() !== 'arm64') {

diff --git a/new-docs/puppeteer.browser.waitfortarget.md b/new-docs/puppeteer.browser.waitfortarget.md
@@ -17,9 +17,11 @@ waitForTarget(predicate: (x: Target) => boolean, options?: {
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean |  |
-|  options | { timeout?: number; } |  {<!-- -->!Promise<!-- -->&lt;<!-- -->!Target<!-- -->&gt;<!-- -->} |
+|  options | { timeout?: number; } |  |
 
 <b>Returns:</b>
 
 Promise&lt;[Target](./puppeteer.target.md)<!-- -->&gt;
 
+{<!-- -->!Promise<!-- -->&lt;<!-- -->!Target<!-- -->&gt;<!-- -->}
+
diff --git a/new-docs/puppeteer.browserfetcher._getfolderpath.md b/new-docs/puppeteer.browserfetcher._getfolderpath.md
@@ -14,9 +14,11 @@ _getFolderPath(revision: string): string;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  revision | string |  {<!-- -->string<!-- -->} |
+|  revision | string |  |
 
 <b>Returns:</b>
 
 string
 
+{<!-- -->string<!-- -->}
+
diff --git a/new-docs/puppeteer.browserfetcher.download.md b/new-docs/puppeteer.browserfetcher.download.md
@@ -15,9 +15,11 @@ download(revision: string, progressCallback: (x: number, y: number) => void): Pr
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  revision | string |  |
-|  progressCallback | (x: number, y: number) =&gt; void |  {<!-- -->!Promise<!-- -->&lt;<!-- -->!BrowserFetcher.RevisionInfo<!-- -->&gt;<!-- -->} |
+|  progressCallback | (x: number, y: number) =&gt; void |  |
 
 <b>Returns:</b>
 
 Promise&lt;BrowserFetcherRevisionInfo&gt;
 
+{<!-- -->!Promise<!-- -->&lt;<!-- -->!BrowserFetcher.RevisionInfo<!-- -->&gt;<!-- -->}
+
diff --git a/new-docs/puppeteer.connection.createsession.md b/new-docs/puppeteer.connection.createsession.md
@@ -14,9 +14,11 @@ createSession(targetInfo: Protocol.Target.TargetInfo): Promise<CDPSession>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  targetInfo | Protocol.Target.TargetInfo |  {<!-- -->!Promise<!-- -->&lt;<!-- -->!CDPSession<!-- -->&gt;<!-- -->} |
+|  targetInfo | Protocol.Target.TargetInfo |  |
 
 <b>Returns:</b>
 
 Promise&lt;[CDPSession](./puppeteer.cdpsession.md)<!-- -->&gt;
 
+{<!-- -->!Promise<!-- -->&lt;<!-- -->!CDPSession<!-- -->&gt;<!-- -->}
+
diff --git a/new-docs/puppeteer.connection.session.md b/new-docs/puppeteer.connection.session.md
@@ -14,9 +14,11 @@ session(sessionId: string): CDPSession | null;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  sessionId | string |  {<!-- -->?CDPSession<!-- -->} |
+|  sessionId | string |  |
 
 <b>Returns:</b>
 
 [CDPSession](./puppeteer.cdpsession.md) \| null
 
+{<!-- -->?CDPSession<!-- -->}
+
diff --git a/new-docs/puppeteer.elementhandle.boxmodel.md b/new-docs/puppeteer.elementhandle.boxmodel.md
@@ -4,8 +4,6 @@
 
 ## ElementHandle.boxModel() method
 
- {<!-- -->!Promise<!-- -->&lt;<!-- -->?BoxModel<!-- -->&gt;<!-- -->}
-
 <b>Signature:</b>
 
 ```typescript
@@ -15,3 +13,5 @@ boxModel(): Promise<BoxModel | null>;
 
 Promise&lt;BoxModel \| null&gt;
 
+{<!-- -->!Promise<!-- -->&lt;<!-- -->?BoxModel<!-- -->&gt;<!-- -->}
+
diff --git a/new-docs/puppeteer.elementhandle.md b/new-docs/puppeteer.elementhandle.md
@@ -39,7 +39,7 @@ export declare class ElementHandle extends JSHandle
 |  [$x(expression)](./puppeteer.elementhandle._x.md) |  |  |
 |  [asElement()](./puppeteer.elementhandle.aselement.md) |  |  |
 |  [boundingBox()](./puppeteer.elementhandle.boundingbox.md) |  |  |
-|  [boxModel()](./puppeteer.elementhandle.boxmodel.md) |  |  {<!-- -->!Promise<!-- -->&lt;<!-- -->?BoxModel<!-- -->&gt;<!-- -->} |
+|  [boxModel()](./puppeteer.elementhandle.boxmodel.md) |  |  |
 |  [click(options)](./puppeteer.elementhandle.click.md) |  |  |
 |  [contentFrame()](./puppeteer.elementhandle.contentframe.md) |  |  |
 |  [focus()](./puppeteer.elementhandle.focus.md) |  |  |

diff --git a/new-docs/puppeteer.httprequest.failure.md b/new-docs/puppeteer.httprequest.failure.md
@@ -4,8 +4,6 @@
 
 ## HTTPRequest.failure() method
 
- {<!-- -->?<!-- -->{<!-- -->errorText: string<!-- -->}<!-- -->}
-
 <b>Signature:</b>
 
 ```typescript
@@ -17,3 +15,5 @@ failure(): {
 
 { errorText: string; } \| null
 
+{<!-- -->?<!-- -->{<!-- -->errorText: string<!-- -->}<!-- -->}
+
diff --git a/new-docs/puppeteer.httprequest.md b/new-docs/puppeteer.httprequest.md
@@ -33,7 +33,7 @@ export declare class HTTPRequest
 |  --- | --- | --- |
 |  [abort(errorCode)](./puppeteer.httprequest.abort.md) |  |  |
 |  [continue(overrides)](./puppeteer.httprequest.continue.md) |  |  |
-|  [failure()](./puppeteer.httprequest.failure.md) |  |  {<!-- -->?<!-- -->{<!-- -->errorText: string<!-- -->}<!-- -->} |
+|  [failure()](./puppeteer.httprequest.failure.md) |  |  |
 |  [frame()](./puppeteer.httprequest.frame.md) |  |  |
 |  [headers()](./puppeteer.httprequest.headers.md) |  |  |
 |  [isNavigationRequest()](./puppeteer.httprequest.isnavigationrequest.md) |  |  |

diff --git a/src/Browser.ts b/src/Browser.ts
@@ -224,7 +224,7 @@ export class Browser extends EventEmitter {
   /**
    * @param {function(!Target):boolean} predicate
    * @param {{timeout?: number}=} options
-   * @return {!Promise<!Target>}
+   * @returns {!Promise<!Target>}
    */
   async waitForTarget(
     predicate: (x: Target) => boolean,

diff --git a/src/BrowserFetcher.ts b/src/BrowserFetcher.ts
@@ -84,7 +84,7 @@ function archiveName(
  * @param {string} platform
  * @param {string} host
  * @param {string} revision
- * @return {string}
+ * @returns {string}
  */
 function downloadURL(
   product: Product,
@@ -211,7 +211,7 @@ export class BrowserFetcher {
   /**
    * @param {string} revision
    * @param {?function(number, number):void} progressCallback
-   * @return {!Promise<!BrowserFetcher.RevisionInfo>}
+   * @returns {!Promise<!BrowserFetcher.RevisionInfo>}
    */
   async download(
     revision: string,
@@ -332,7 +332,7 @@ export class BrowserFetcher {
 
   /**
    * @param {string} revision
-   * @return {string}
+   * @returns {string}
    */
   _getFolderPath(revision: string): string {
     return path.join(this._downloadsFolder, this._platform + '-' + revision);
@@ -355,7 +355,7 @@ function parseFolderPath(
  * @param {string} url
  * @param {string} destinationPath
  * @param {?function(number, number):void} progressCallback
- * @return {!Promise}
+ * @returns {!Promise}
  */
 function downloadFile(
   url: string,
@@ -417,7 +417,7 @@ function install(archivePath: string, folderPath: string): Promise<unknown> {
 /**
  * @param {string} tarPath
  * @param {string} folderPath
- * @return {!Promise<?Error>}
+ * @returns {!Promise<?Error>}
  */
 function extractTar(tarPath: string, folderPath: string): Promise<unknown> {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -441,7 +441,7 @@ function extractTar(tarPath: string, folderPath: string): Promise<unknown> {
  *
  * @param {string} dmgPath
  * @param {string} folderPath
- * @return {!Promise<?Error>}
+ * @returns {!Promise<?Error>}
  */
 function installDMG(dmgPath: string, folderPath: string): Promise<void> {
   let mountPath;

diff --git a/src/Connection.ts b/src/Connection.ts
@@ -55,7 +55,7 @@ export class Connection extends EventEmitter {
 
   /**
    * @param {string} sessionId
-   * @return {?CDPSession}
+   * @returns {?CDPSession}
    */
   session(sessionId: string): CDPSession | null {
     return this._sessions.get(sessionId) || null;
@@ -146,7 +146,7 @@ export class Connection extends EventEmitter {
 
   /**
    * @param {Protocol.Target.TargetInfo} targetInfo
-   * @return {!Promise<!CDPSession>}
+   * @returns {!Promise<!CDPSession>}
    */
   async createSession(
     targetInfo: Protocol.Target.TargetInfo
@@ -248,7 +248,7 @@ export class CDPSession extends EventEmitter {
  * @param {!Error} error
  * @param {string} method
  * @param {{error: {message: string, data: any}}} object
- * @return {!Error}
+ * @returns {!Error}
  */
 function createProtocolError(
   error: Error,
@@ -263,7 +263,7 @@ function createProtocolError(
 /**
  * @param {!Error} error
  * @param {string} message
- * @return {!Error}
+ * @returns {!Error}
  */
 function rewriteError(error: Error, message: string): Error {
   error.message = message;

diff --git a/src/DOMWorld.ts b/src/DOMWorld.ts
@@ -93,7 +93,7 @@ export class DOMWorld {
   }
 
   /**
-   * @return {!Promise<!ExecutionContext>}
+   * @returns {!Promise<!ExecutionContext>}
    */
   executionContext(): Promise<ExecutionContext> {
     if (this._detached)
@@ -106,7 +106,7 @@ export class DOMWorld {
   /**
    * @param {Function|string} pageFunction
    * @param {!Array<*>} args
-   * @return {!Promise<!JSHandle>}
+   * @returns {!Promise<!JSHandle>}
    */
   async evaluateHandle(
     pageFunction: Function | string,
@@ -119,7 +119,7 @@ export class DOMWorld {
   /**
    * @param {Function|string} pageFunction
    * @param {!Array<*>} args
-   * @return {!Promise<*>}
+   * @returns {!Promise<*>}
    */
   async evaluate<ReturnType extends any>(
     pageFunction: Function | string,
@@ -131,7 +131,7 @@ export class DOMWorld {
 
   /**
    * @param {string} selector
-   * @return {!Promise<?ElementHandle>}
+   * @returns {!Promise<?ElementHandle>}
    */
   async $(selector: string): Promise<ElementHandle | null> {
     const document = await this._document();
@@ -179,7 +179,7 @@ export class DOMWorld {
 
   /**
    * @param {string} selector
-   * @return {!Promise<!Array<!ElementHandle>>}
+   * @returns {!Promise<!Array<!ElementHandle>>}
    */
   async $$(selector: string): Promise<ElementHandle[]> {
     const document = await this._document();
@@ -232,7 +232,7 @@ export class DOMWorld {
 
   /**
    * @param {!{url?: string, path?: string, content?: string, type?: string}} options
-   * @return {!Promise<!ElementHandle>}
+   * @returns {!Promise<!ElementHandle>}
    */
   async addScriptTag(options: {
     url?: string;
@@ -497,7 +497,7 @@ export class DOMWorld {
      * @param {boolean} isXPath
      * @param {boolean} waitForVisible
      * @param {boolean} waitForHidden
-     * @return {?Node|boolean}
+     * @returns {?Node|boolean}
      */
     function predicate(
       selectorOrXPath: string,
@@ -690,7 +690,7 @@ async function waitForPredicatePageFunction(
   if (typeof polling === 'number') return await pollInterval(polling);
 
   /**
-   * @return {!Promise<*>}
+   * @returns {!Promise<*>}
    */
   async function pollMutation(): Promise<unknown> {
     const success = await predicate(...args);

diff --git a/src/ExecutionContext.ts b/src/ExecutionContext.ts
@@ -149,7 +149,7 @@ export class ExecutionContext {
 
     /**
      * @param {*} arg
-     * @return {*}
+     * @returns {*}
      * @this {ExecutionContext}
      */
     function convertArgument(this: ExecutionContext, arg: unknown): unknown {

diff --git a/src/HTTPRequest.ts b/src/HTTPRequest.ts
@@ -102,7 +102,7 @@ export class HTTPRequest {
   }
 
   /**
-   * @return {?{errorText: string}}
+   * @returns {?{errorText: string}}
    */
   failure(): { errorText: string } | null {
     if (!this._failureText) return null;

diff --git a/src/JSHandle.ts b/src/JSHandle.ts
@@ -437,7 +437,7 @@ export class ElementHandle extends JSHandle {
   }
 
   /**
-   * @return {!Promise<?BoxModel>}
+   * @returns {!Promise<?BoxModel>}
    */
   async boxModel(): Promise<BoxModel | null> {
     const result = await this._getBoxModel();

diff --git a/src/Launcher.ts b/src/Launcher.ts
@@ -154,7 +154,7 @@ class ChromeLauncher implements ProductLauncher {
 
   /**
    * @param {!Launcher.ChromeArgOptions=} options
-   * @return {!Array<string>}
+   * @returns {!Array<string>}
    */
   defaultArgs(options: ChromeArgOptions = {}): string[] {
     const chromeArguments = [

diff --git a/src/LifecycleWatcher.ts b/src/LifecycleWatcher.ts
@@ -212,7 +212,7 @@ export class LifecycleWatcher {
     /**
      * @param {!Frame} frame
      * @param {!Array<string>} expectedLifecycle
-     * @return {boolean}
+     * @returns {boolean}
      */
     function checkLifecycle(
       frame: Frame,

diff --git a/test/golden-utils.js b/test/golden-utils.js
@@ -33,7 +33,7 @@ const GoldenComparators = {
  * @param {?Object} actualBuffer
  * @param {!Buffer} expectedBuffer
  * @param {!string} mimeType
- * @return {?{diff: (!Object:undefined), errorMessage: (string|undefined)}}
+ * @returns {?{diff: (!Object:undefined), errorMessage: (string|undefined)}}
  */
 function compareImages(actualBuffer, expectedBuffer, mimeType) {
   if (!actualBuffer || !(actualBuffer instanceof Buffer))
@@ -67,7 +67,7 @@ function compareImages(actualBuffer, expectedBuffer, mimeType) {
 /**
  * @param {?Object} actual
  * @param {!Buffer} expectedBuffer
- * @return {?{diff: (!Object:undefined), errorMessage: (string|undefined)}}
+ * @returns {?{diff: (!Object:undefined), errorMessage: (string|undefined)}}
  */
 function compareText(actual, expectedBuffer) {
   if (typeof actual !== 'string')
@@ -89,7 +89,7 @@ function compareText(actual, expectedBuffer) {
 /**
  * @param {?Object} actual
  * @param {string} goldenName
- * @return {!{pass: boolean, message: (undefined|string)}}
+ * @returns {!{pass: boolean, message: (undefined|string)}}
  */
 function compare(goldenPath, outputPath, actual, goldenName) {
   goldenPath = path.normalize(goldenPath);
@@ -149,7 +149,7 @@ function compare(goldenPath, outputPath, actual, goldenName) {
  * @param {string} filePath
  * @param {string} suffix
  * @param {string=} customExtension
- * @return {string}
+ * @returns {string}
  */
 function addSuffix(filePath, suffix, customExtension) {
   const dirname = path.dirname(filePath);

diff --git a/test/requestinterception.spec.js b/test/requestinterception.spec.js
@@ -693,7 +693,7 @@ describe('request interception', function () {
 
 /**
  * @param {string} path
- * @return {string}
+ * @returns {string}
  */
 function pathToFileURL(path) {
   let pathName = path.replace(/\\/g, '/');