From ca3a58f93a107eb6ead9e8376a7ba32c567cd174 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 18:14:29 +0200 Subject: [PATCH] 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 | 2 +- extensions/chromium/pdfHandler.js | 12 ++--- src/core/annotation.js | 9 ++-- src/core/core_utils.js | 2 +- src/core/evaluator.js | 2 +- src/core/fonts.js | 2 +- src/display/api.js | 65 ++++++++++++------------- src/display/content_disposition.js | 2 +- src/display/display_utils.js | 12 ++--- src/shared/message_handler.js | 2 +- src/shared/util.js | 2 +- web/base_viewer.js | 2 +- web/firefoxcom.js | 2 +- web/grab_to_pan.js | 6 +-- web/preferences.js | 24 ++++----- web/ui_utils.js | 8 +-- 16 files changed, 77 insertions(+), 77 deletions(-) diff --git a/extensions/chromium/extension-router.js b/extensions/chromium/extension-router.js index 2cefcda29..6b222aca7 100644 --- 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); diff --git a/extensions/chromium/pdfHandler.js b/extensions/chromium/pdfHandler.js index 3ddea7486..630d5fb55 100644 --- 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; diff --git a/src/core/annotation.js b/src/core/annotation.js index 156bf1ab2..f932beabd 100644 --- 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) { diff --git a/src/core/core_utils.js b/src/core/core_utils.js index 694342fa9..b18124dad 100644 --- 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, diff --git a/src/core/evaluator.js b/src/core/evaluator.js index 91d7b610d..b4d0ae68d 100644 --- 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) { diff --git a/src/core/fonts.js b/src/core/fonts.js index 04eab4c27..9fe3c8acf 100644 --- 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 diff --git a/src/display/api.js b/src/display/api.js index 52f4cbfc7..d6d41102f 100644 --- 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); diff --git a/src/display/content_disposition.js b/src/display/content_disposition.js index 638e715f2..67a756f5d 100644 --- 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; diff --git a/src/display/display_utils.js b/src/display/display_utils.js index aa671c802..2cf65b23c 100644 --- 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)) { diff --git a/src/shared/message_handler.js b/src/shared/message_handler.js index bed45e28a..97c1fe5cc 100644 --- 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++; diff --git a/src/shared/util.js b/src/shared/util.js index 6de6d297a..589bb4887 100644 --- 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); diff --git a/web/base_viewer.js b/web/base_viewer.js index be5b71e62..7c38fa471 100644 --- 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) { diff --git a/web/firefoxcom.js b/web/firefoxcom.js index 05d31420f..0717f5271 100644 --- 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(''); diff --git a/web/grab_to_pan.js b/web/grab_to_pan.js index b0e68c254..0ac9228f4 100644 --- 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) { diff --git a/web/preferences.js b/web/preferences.js index ba3b1b53e..5e6320438 100644 --- 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; diff --git a/web/ui_utils.js b/web/ui_utils.js index 941db2383..4dfe05f13 100644 --- 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, }) {