Consistently use @returns for returned data types in JSDoc comments

Sometimes we also used `@return`, but `@returns` is what the JSDoc
documentation recommends. Even though `@return` works as an alias, it's
good to use the recommended syntax and to be consistent within the
project.

extensions/chromium/extension-router.js

@@ -36,7 +36,7 @@ limitations under the License.
 
   /**
    * @param {string} url The URL prefixed with chrome-extension://.../
-   * @return {string|undefined} The percent-encoded URL of the (PDF) file.
+   * @returns {string|undefined} The percent-encoded URL of the (PDF) file.
    */
   function parseExtensionURL(url) {
     url = url.substring(CRX_BASE_URL.length);

extensions/chromium/pdfHandler.js

@@ -26,7 +26,7 @@ function getViewerURL(pdf_url) {
 /**
  * @param {Object} details First argument of the webRequest.onHeadersReceived
  *                         event. The property "url" is read.
- * @return {boolean} True if the PDF file should be downloaded.
+ * @returns {boolean} True if the PDF file should be downloaded.
  */
 function isPdfDownloadable(details) {
   if (details.url.includes('pdfjs.action=download')) {
@@ -50,7 +50,7 @@ function isPdfDownloadable(details) {
 /**
  * Get the header from the list of headers for a given name.
  * @param {Array} headers responseHeaders of webRequest.onHeadersReceived
- * @return {undefined|{name: string, value: string}} The header, if found.
+ * @returns {undefined|{name: string, value: string}} The header, if found.
  */
 function getHeaderFromHeaders(headers, headerName) {
   for (var i = 0; i < headers.length; ++i) {
@@ -67,7 +67,7 @@ function getHeaderFromHeaders(headers, headerName) {
  * @param {Object} details First argument of the webRequest.onHeadersReceived
  *                         event. The properties "responseHeaders" and "url"
  *                         are read.
- * @return {boolean} True if the resource is a PDF file.
+ * @returns {boolean} True if the resource is a PDF file.
  */
 function isPdfFile(details) {
   var header = getHeaderFromHeaders(details.responseHeaders, 'content-type');
@@ -95,9 +95,9 @@ function isPdfFile(details) {
  * @param {Object} details First argument of the webRequest.onHeadersReceived
  *                         event. The property "responseHeaders" is read and
  *                         modified if needed.
- * @return {Object|undefined} The return value for the onHeadersReceived event.
+ * @returns {Object|undefined} The return value for the onHeadersReceived event.
- *                            Object with key "responseHeaders" if the headers
+ *                             Object with key "responseHeaders" if the headers
- *                            have been modified, undefined otherwise.
+ *                             have been modified, undefined otherwise.
  */
 function getHeadersWithContentDispositionAttachment(details) {
   var headers = details.responseHeaders;

src/core/annotation.js

@@ -36,7 +36,8 @@ class AnnotationFactory {
    * @param {Object} ref
    * @param {PDFManager} pdfManager
    * @param {Object} idFactory
-   * @return {Promise} A promise that is resolved with an {Annotation} instance.
+   * @returns {Promise} A promise that is resolved with an {Annotation}
+   *   instance.
    */
   static create(xref, ref, pdfManager, idFactory) {
     return pdfManager.ensure(this, '_create',
@@ -318,7 +319,7 @@ class Annotation {
    * @memberof Annotation
    * @param {number} flag - Hexadecimal representation for an annotation
    *                        characteristic
-   * @return {boolean}
+   * @returns {boolean}
    * @see {@link shared/util.js}
    */
   hasFlag(flag) {
@@ -780,7 +781,7 @@ class WidgetAnnotation extends Annotation {
    * @private
    * @memberof WidgetAnnotation
    * @param {Dict} dict - Complete widget annotation dictionary
-   * @return {string}
+   * @returns {string}
    */
   _constructFieldName(dict) {
     // Both the `Parent` and `T` fields are optional. While at least one of
@@ -826,7 +827,7 @@ class WidgetAnnotation extends Annotation {
    * @memberof WidgetAnnotation
    * @param {number} flag - Hexadecimal representation for an annotation
    *                        field characteristic
-   * @return {boolean}
+   * @returns {boolean}
    * @see {@link shared/util.js}
    */
   hasFieldFlag(flag) {

src/core/core_utils.js

@@ -98,7 +98,7 @@ const ROMAN_NUMBER_MAP = [
  * @param {number} number - The number that should be converted.
  * @param {boolean} lowerCase - Indicates if the result should be converted
  *   to lower case letters. The default value is `false`.
- * @return {string} The resulting Roman number.
+ * @returns {string} The resulting Roman number.
  */
 function toRomanNumerals(number, lowerCase = false) {
   assert(Number.isInteger(number) && number > 0,

src/core/evaluator.js

@@ -2095,7 +2095,7 @@ var PartialEvaluator = (function PartialEvaluatorClosure() {
     /**
      * Builds a char code to unicode map based on section 9.10 of the spec.
      * @param {Object} properties Font properties object.
-     * @return {Promise} A Promise that is resolved with a
+     * @returns {Promise} A Promise that is resolved with a
      *   {ToUnicodeMap|IdentityToUnicodeMap} object.
      */
     buildToUnicode(properties) {

src/core/fonts.js

@@ -732,7 +732,7 @@ var Font = (function FontClosure() {
    * private use area. This is done to avoid issues with various problematic
    * unicode areas where either a glyph won't be drawn or is deformed by a
    * shaper.
-   * @return {Object} Two properties:
+   * @returns {Object} Two properties:
    * 'toFontChar' - maps original char codes(the value that will be read
    * from commands such as show text) to the char codes that will be used in the
    * font that we build

src/display/api.js

@@ -105,7 +105,7 @@ if (typeof PDFJSDev !== 'undefined' && PDFJSDev.test('GENERIC')) {
  * @typedef {function} IPDFStreamFactory
  * @param {DocumentInitParameters} params The document initialization
  * parameters. The "url" key is always present.
- * @return {IPDFStream}
+ * @returns {IPDFStream}
  */
 
 /** @type IPDFStreamFactory */
@@ -217,8 +217,7 @@ function setPDFNetworkStreamFactory(pdfNetworkStreamFactory) {
  * @param {string|TypedArray|DocumentInitParameters|PDFDataRangeTransport} src
  * Can be a url to where a PDF is located, a typed array (Uint8Array)
  * already populated with data or parameter object.
- *
+ * @returns {PDFDocumentLoadingTask}
- * @return {PDFDocumentLoadingTask}
  */
 function getDocument(src) {
   const task = new PDFDocumentLoadingTask();
@@ -475,8 +474,8 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() {
 
     /**
      * Aborts all network requests and destroys worker.
-     * @return {Promise} A promise that is resolved after destruction activity
+     * @returns {Promise} A promise that is resolved after destruction activity
-     *                   is completed.
+     *                    is completed.
      */
     destroy() {
       this.destroyed = true;
@@ -606,7 +605,7 @@ class PDFDocumentProxy {
 
   /**
    * @param {number} pageNumber - The page number to get. The first page is 1.
-   * @return {Promise} A promise that is resolved with a {@link PDFPageProxy}
+   * @returns {Promise} A promise that is resolved with a {@link PDFPageProxy}
    *   object.
    */
   getPage(pageNumber) {
@@ -616,7 +615,7 @@ class PDFDocumentProxy {
   /**
    * @param {{num: number, gen: number}} ref - The page reference. Must have
    *   the `num` and `gen` properties.
-   * @return {Promise} A promise that is resolved with the page index that is
+   * @returns {Promise} A promise that is resolved with the page index that is
    *   associated with the reference.
    */
   getPageIndex(ref) {
@@ -624,7 +623,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with a lookup table for
+   * @returns {Promise} A promise that is resolved with a lookup table for
    *   mapping named destinations to reference numbers.
    *
    * This can be slow for large documents. Use `getDestination` instead.
@@ -635,7 +634,7 @@ class PDFDocumentProxy {
 
   /**
    * @param {string} id - The named destination to get.
-   * @return {Promise} A promise that is resolved with all information
+   * @returns {Promise} A promise that is resolved with all information
    *   of the given named destination.
    */
   getDestination(id) {
@@ -643,7 +642,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Array} containing
+   * @returns {Promise} A promise that is resolved with an {Array} containing
    *   the page labels that correspond to the page indexes, or `null` when
    *   no page labels are present in the PDF file.
    */
@@ -652,7 +651,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with a {string} containing
+   * @returns {Promise} A promise that is resolved with a {string} containing
    *   the page layout name.
    */
   getPageLayout() {
@@ -660,7 +659,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with a {string} containing
+   * @returns {Promise} A promise that is resolved with a {string} containing
    *   the page mode name.
    */
   getPageMode() {
@@ -668,7 +667,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Object} containing
+   * @returns {Promise} A promise that is resolved with an {Object} containing
    *   the viewer preferences.
    */
   getViewerPreferences() {
@@ -676,15 +675,15 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Array} containing the
+   * @returns {Promise} A promise that is resolved with an {Array} containing
-   *   destination, or `null` when no open action is present in the PDF file.
+   *   the destination, or `null` when no open action is present in the PDF.
    */
   getOpenActionDestination() {
     return this._transport.getOpenActionDestination();
   }
 
   /**
-   * @return {Promise} A promise that is resolved with a lookup table for
+   * @returns {Promise} A promise that is resolved with a lookup table for
    *   mapping named attachments to their content.
    */
   getAttachments() {
@@ -692,7 +691,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Array} of all the
+   * @returns {Promise} A promise that is resolved with an {Array} of all the
    *   JavaScript strings in the name tree, or `null` if no JavaScript exists.
    */
   getJavaScript() {
@@ -700,7 +699,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Array} that is a
+   * @returns {Promise} A promise that is resolved with an {Array} that is a
    * tree outline (if it has one) of the PDF. The tree is in the format of:
    * [
    *   {
@@ -721,7 +720,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Array} that contains
+   * @returns {Promise} A promise that is resolved with an {Array} that contains
    *   the permission flags for the PDF document, or `null` when
    *   no permissions are present in the PDF file.
    */
@@ -730,7 +729,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with an {Object} that has
+   * @returns {Promise} A promise that is resolved with an {Object} that has
    *   `info` and `metadata` properties. `info` is an {Object} filled with
    *   anything available in the information dictionary and similarly
    *   `metadata` is a {Metadata} object with information from the metadata
@@ -741,15 +740,15 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise that is resolved with a {TypedArray} that has
+   * @returns {Promise} A promise that is resolved with a {TypedArray} that has
-   * the raw data from the PDF.
+   *   the raw data from the PDF.
    */
   getData() {
     return this._transport.getData();
   }
 
   /**
-   * @return {Promise} A promise that is resolved when the document's data
+   * @returns {Promise} A promise that is resolved when the document's data
    *   is loaded. It is resolved with an {Object} that contains the `length`
    *   property that indicates size of the PDF data in bytes.
    */
@@ -758,7 +757,7 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @return {Promise} A promise this is resolved with current statistics about
+   * @returns {Promise} A promise this is resolved with current statistics about
    *   document structures (see {@link PDFDocumentStats}).
    */
   getStats() {
@@ -953,7 +952,7 @@ class PDFPageProxy {
 
   /**
    * @param {GetViewportParameters} params - Viewport parameters.
-   * @return {PageViewport} Contains 'width' and 'height' properties
+   * @returns {PageViewport} Contains 'width' and 'height' properties
    *   along with transforms required for rendering.
    */
   getViewport({ scale, rotation = this.rotate, dontFlip = false, } = {}) {
@@ -972,8 +971,8 @@ class PDFPageProxy {
 
   /**
    * @param {GetAnnotationsParameters} params - Annotation parameters.
-   * @return {Promise} A promise that is resolved with an {Array} of the
+   * @returns {Promise} A promise that is resolved with an {Array} of the
-   * annotation objects.
+   *   annotation objects.
    */
   getAnnotations({ intent = null, } = {}) {
     if (!this.annotationsPromise || this.annotationsIntent !== intent) {
@@ -987,8 +986,8 @@ class PDFPageProxy {
   /**
    * Begins the process of rendering a page to the desired context.
    * @param {RenderParameters} params Page render parameters.
-   * @return {RenderTask} An object that contains the promise, which
+   * @returns {RenderTask} An object that contains the promise, which
-   *                      is resolved when the page finishes rendering.
+   *                       is resolved when the page finishes rendering.
    */
   render({ canvasContext, viewport, intent = 'display', enableWebGL = false,
            renderInteractiveForms = false, transform = null, imageLayer = null,
@@ -1101,7 +1100,7 @@ class PDFPageProxy {
   }
 
   /**
-   * @return {Promise} A promise resolved with an {@link PDFOperatorList}
+   * @returns {Promise} A promise resolved with an {@link PDFOperatorList}
    *   object that represents page's operator list.
    */
   getOperatorList() {
@@ -1146,7 +1145,7 @@ class PDFPageProxy {
 
   /**
    * @param {getTextContentParameters} params - getTextContent parameters.
-   * @return {ReadableStream} ReadableStream to read textContent chunks.
+   * @returns {ReadableStream} ReadableStream to read textContent chunks.
    */
   streamTextContent({ normalizeWhitespace = false,
                       disableCombineTextItems = false, } = {}) {
@@ -1166,8 +1165,8 @@ class PDFPageProxy {
 
   /**
    * @param {getTextContentParameters} params - getTextContent parameters.
-   * @return {Promise} That is resolved a {@link TextContent}
+   * @returns {Promise} That is resolved a {@link TextContent}
-   * object that represent the page text content.
+   *   object that represent the page text content.
    */
   getTextContent(params = {}) {
     const readableStream = this.streamTextContent(params);

src/display/content_disposition.js

@@ -25,7 +25,7 @@
  * Extract file name from the Content-Disposition HTTP response header.
  *
  * @param {string} contentDisposition
- * @return {string} Filename, if found in the Content-Disposition header.
+ * @returns {string} Filename, if found in the Content-Disposition header.
  */
 function getFilenameFromContentDispositionHeader(contentDisposition) {
   let needsEncodingFixup = true;

src/display/display_utils.js

@@ -252,7 +252,7 @@ class PageViewport {
   /**
    * Clones viewport, with optional additional properties.
    * @param {PageViewportCloneParameters} [params]
-   * @return {PageViewport} Cloned viewport.
+   * @returns {PageViewport} Cloned viewport.
    */
   clone({ scale = this.scale, rotation = this.rotation,
           dontFlip = false, } = {}) {
@@ -271,7 +271,7 @@ class PageViewport {
    * converting PDF location into canvas pixel coordinates.
    * @param {number} x - The x-coordinate.
    * @param {number} y - The y-coordinate.
-   * @return {Object} Object containing `x` and `y` properties of the
+   * @returns {Object} Object containing `x` and `y` properties of the
    *   point in the viewport coordinate space.
    * @see {@link convertToPdfPoint}
    * @see {@link convertToViewportRectangle}
@@ -283,8 +283,8 @@ class PageViewport {
   /**
    * Converts PDF rectangle to the viewport coordinates.
    * @param {Array} rect - The xMin, yMin, xMax and yMax coordinates.
-   * @return {Array} Array containing corresponding coordinates of the rectangle
+   * @returns {Array} Array containing corresponding coordinates of the
-   *   in the viewport coordinate space.
+   *   rectangle in the viewport coordinate space.
    * @see {@link convertToViewportPoint}
    */
   convertToViewportRectangle(rect) {
@@ -298,7 +298,7 @@ class PageViewport {
    * for converting canvas pixel location into PDF one.
    * @param {number} x - The x-coordinate.
    * @param {number} y - The y-coordinate.
-   * @return {Object} Object containing `x` and `y` properties of the
+   * @returns {Object} Object containing `x` and `y` properties of the
    *   point in the PDF coordinate space.
    * @see {@link convertToViewportPoint}
    */
@@ -514,7 +514,7 @@ class PDFDateString {
   * parts of the date string).
   *
   * @param {string} input
-  * @return {Date|null}
+  * @returns {Date|null}
   */
   static toDateObject(input) {
     if (!input || !isString(input)) {

src/shared/message_handler.js

@@ -177,7 +177,7 @@ MessageHandler.prototype = {
    * @param {Object} queueingStrategy - Strategy to signal backpressure based on
    *                 internal queue.
    * @param {Array} [transfers] - List of transfers/ArrayBuffers.
-   * @return {ReadableStream} ReadableStream to read data in chunks.
+   * @returns {ReadableStream} ReadableStream to read data in chunks.
    */
   sendWithStream(actionName, data, queueingStrategy, transfers) {
     let streamId = this.streamId++;

src/shared/util.js

@@ -820,7 +820,7 @@ function isSpace(ch) {
  * Creates a promise capability object.
  * @alias createPromiseCapability
  *
- * @return {PromiseCapability}
+ * @returns {PromiseCapability}
  */
 function createPromiseCapability() {
   const capability = Object.create(null);

web/base_viewer.js

@@ -209,7 +209,7 @@ class BaseViewer {
   }
 
   /**
-   * @return {boolean} Whether the pageNumber is valid (within bounds).
+   * @returns {boolean} Whether the pageNumber is valid (within bounds).
    * @private
    */
   _setCurrentPageNumber(val, resetCurrentPageView = false) {

web/firefoxcom.js

@@ -34,7 +34,7 @@ let FirefoxCom = (function FirefoxComClosure() {
      * be able to synchronously reply.
      * @param {string} action - The action to trigger.
      * @param {string} [data] - The data to send.
-     * @return {*} The response.
+     * @returns {*} The response.
      */
     requestSync(action, data) {
       let request = document.createTextNode('');

web/grab_to_pan.js

@@ -93,7 +93,7 @@ GrabToPan.prototype = {
    * Override this method to change the default behaviour.
    *
    * @param node {Element} The target of the event
-   * @return {boolean} Whether to not react to the click event.
+   * @returns {boolean} Whether to not react to the click event.
    */
   ignoreTarget: function GrabToPan_ignoreTarget(node) {
     // Use matchesSelector to check whether the clicked element
@@ -205,8 +205,8 @@ var isSafari6plus = /Apple/.test(navigator.vendor) &&
 /**
  * Whether the left mouse is not pressed.
  * @param event {MouseEvent}
- * @return {boolean} True if the left mouse button is not pressed.
+ * @returns {boolean} True if the left mouse button is not pressed,
- *                   False if unsure or if the left mouse button is pressed.
+ *                    False if unsure or if the left mouse button is pressed.
  */
 function isLeftMouseReleased(event) {
   if ('buttons' in event && isNotIEorIsIE10plus) {

web/preferences.js

@@ -83,8 +83,8 @@ class BasePreferences {
   /**
    * Stub function for writing preferences to storage.
    * @param {Object} prefObj The preferences that should be written to storage.
-   * @return {Promise} A promise that is resolved when the preference values
+   * @returns {Promise} A promise that is resolved when the preference values
-   *                   have been written.
+   *                    have been written.
    */
   async _writeToStorage(prefObj) {
     throw new Error('Not implemented: _writeToStorage');
@@ -93,8 +93,8 @@ class BasePreferences {
   /**
    * Stub function for reading preferences from storage.
    * @param {Object} prefObj The preferences that should be read from storage.
-   * @return {Promise} A promise that is resolved with an {Object} containing
+   * @returns {Promise} A promise that is resolved with an {Object} containing
-   *                   the preferences that have been read.
+   *                    the preferences that have been read.
    */
   async _readFromStorage(prefObj) {
     throw new Error('Not implemented: _readFromStorage');
@@ -102,8 +102,8 @@ class BasePreferences {
 
   /**
    * Reset the preferences to their default values and update storage.
-   * @return {Promise} A promise that is resolved when the preference values
+   * @returns {Promise} A promise that is resolved when the preference values
-   *                   have been reset.
+   *                    have been reset.
    */
   async reset() {
     await this._initializedPromise;
@@ -115,8 +115,8 @@ class BasePreferences {
    * Set the value of a preference.
    * @param {string} name The name of the preference that should be changed.
    * @param {boolean|number|string} value The new value of the preference.
-   * @return {Promise} A promise that is resolved when the value has been set,
+   * @returns {Promise} A promise that is resolved when the value has been set,
-   *                   provided that the preference exists and the types match.
+   *                    provided that the preference exists and the types match.
    */
   async set(name, value) {
     await this._initializedPromise;
@@ -149,8 +149,8 @@ class BasePreferences {
   /**
    * Get the value of a preference.
    * @param {string} name The name of the preference whose value is requested.
-   * @return {Promise} A promise that is resolved with a {boolean|number|string}
+   * @returns {Promise} A promise resolved with a {boolean|number|string}
-   *                   containing the value of the preference.
+   *                    containing the value of the preference.
    */
   async get(name) {
     await this._initializedPromise;
@@ -170,8 +170,8 @@ class BasePreferences {
 
   /**
    * Get the values of all preferences.
-   * @return {Promise} A promise that is resolved with an {Object} containing
+   * @returns {Promise} A promise that is resolved with an {Object} containing
-   *                   the values of all preferences.
+   *                    the values of all preferences.
    */
   async getAll() {
     await this._initializedPromise;

web/ui_utils.js

@@ -87,9 +87,9 @@ let NullL10n = {
 
 /**
  * Returns scale factor for the canvas. It makes sense for the HiDPI displays.
- * @return {Object} The object with horizontal (sx) and vertical (sy)
+ * @returns {Object} The object with horizontal (sx) and vertical (sy)
-                    scales. The scaled property is set to false if scaling is
+ *                   scales. The scaled property is set to false if scaling is
-                    not required, true otherwise.
+ *                   not required, true otherwise.
  */
 function getOutputScale(ctx) {
   let devicePixelRatio = window.devicePixelRatio || 1;
@@ -296,7 +296,7 @@ function roundToDivide(x, div) {
  * Gets the size of the specified page, converted from PDF units to inches.
  * @param {Object} An Object containing the properties: {Array} `view`,
  *   {number} `userUnit`, and {number} `rotate`.
- * @return {Object} An Object containing the properties: {number} `width`
+ * @returns {Object} An Object containing the properties: {number} `width`
  *   and {number} `height`, given in inches.
  */
 function getPageSizeInches({ view, userUnit, rotate, }) {