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.
2019-10-12 18:14:29 +02:00 · 2019-10-12 18:14:29 +02:00 · ca3a58f93a
commit ca3a58f93a
parent 8b4ae6f3eb
16 changed files with 77 additions and 77 deletions
--- a/extensions/chromium/extension-router.js
+++ b/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);
--- a/extensions/chromium/pdfHandler.js
+++ b/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.
- *                            Object with key "responseHeaders" if the headers
- *                            have been modified, undefined otherwise.
+ * @returns {Object|undefined} The return value for the onHeadersReceived event.
+ *                             Object with key "responseHeaders" if the headers
+ *                             have been modified, undefined otherwise.
 */
 function getHeadersWithContentDispositionAttachment(details) {
  var headers = details.responseHeaders;
--- a/src/core/annotation.js
+++ b/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) {
--- a/src/core/core_utils.js
+++ b/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,
--- a/src/core/evaluator.js
+++ b/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) {
--- a/src/core/fonts.js
+++ b/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
--- a/src/display/api.js
+++ b/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.
- *
- * @return {PDFDocumentLoadingTask}
+ * @returns {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
-     *                   is completed.
+     * @returns {Promise} A promise that is resolved after destruction activity
+     *                    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
-   *   destination, or `null` when no open action is present in the PDF file.
+   * @returns {Promise} A promise that is resolved with an {Array} containing
+   *   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
-   * the raw data from the PDF.
+   * @returns {Promise} A promise that is resolved with a {TypedArray} that has
+   *   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
-   * annotation objects.
+   * @returns {Promise} A promise that is resolved with an {Array} of the
+   *   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
-   *                      is resolved when the page finishes rendering.
+   * @returns {RenderTask} An object that contains the promise, which
+   *                       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}
-   * object that represent the page text content.
+   * @returns {Promise} That is resolved a {@link TextContent}
+   *   object that represent the page text content.
   */
  getTextContent(params = {}) {
    const readableStream = this.streamTextContent(params);
--- a/src/display/content_disposition.js
+++ b/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;
--- a/src/display/display_utils.js
+++ b/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
-   *   in the viewport coordinate space.
+   * @returns {Array} Array containing corresponding coordinates of the
+   *   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)) {
--- a/src/shared/message_handler.js
+++ b/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++;
--- a/src/shared/util.js
+++ b/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);
--- a/web/base_viewer.js
+++ b/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) {
--- a/web/firefoxcom.js
+++ b/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('');
--- a/web/grab_to_pan.js
+++ b/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.
- *                   False if unsure or if the left mouse button is pressed.
+ * @returns {boolean} True if the left mouse button is not pressed,
+ *                    False if unsure or if the left mouse button is pressed.
 */
 function isLeftMouseReleased(event) {
  if ('buttons' in event && isNotIEorIsIE10plus) {
--- a/web/preferences.js
+++ b/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
-   *                   have been written.
+   * @returns {Promise} A promise that is resolved when the preference values
+   *                    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
-   *                   the preferences that have been read.
+   * @returns {Promise} A promise that is resolved with an {Object} containing
+   *                    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
-   *                   have been reset.
+   * @returns {Promise} A promise that is resolved when the preference values
+   *                    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,
-   *                   provided that the preference exists and the types match.
+   * @returns {Promise} A promise that is resolved when the value has been set,
+   *                    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}
-   *                   containing the value of the preference.
+   * @returns {Promise} A promise resolved with a {boolean|number|string}
+   *                    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
-   *                   the values of all preferences.
+   * @returns {Promise} A promise that is resolved with an {Object} containing
+   *                    the values of all preferences.
   */
  async getAll() {
    await this._initializedPromise;
--- a/web/ui_utils.js
+++ b/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)
-                    scales. The scaled property is set to false if scaling is
-                    not required, true otherwise.
+ * @returns {Object} The object with horizontal (sx) and vertical (sy)
+ *                   scales. The scaled property is set to false if scaling is
+ *                   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, }) {