From e75991b49ed06fec3d053d77d0be17ef67da1379 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 15:54:17 +0200 Subject: [PATCH 1/9] Consistently use `number` for numeric data types in JSDoc comments Sometimes we also used `Number` and `integer`, but `number` is what the JSDoc documentation recommends. --- src/core/annotation.js | 6 +++--- src/core/colorspace.js | 12 ++++++------ src/core/core_utils.js | 2 +- src/core/image.js | 10 +++++----- web/ui_utils.js | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/core/annotation.js b/src/core/annotation.js index 8fd3605be..fbfd88056 100644 --- a/src/core/annotation.js +++ b/src/core/annotation.js @@ -530,7 +530,7 @@ class AnnotationBorderStyle { * * @public * @memberof AnnotationBorderStyle - * @param {integer} width - The width. + * @param {number} width - The width. * @param {Array} rect - The annotation `Rect` entry. */ setWidth(width, rect = [0, 0, 0, 0]) { @@ -642,7 +642,7 @@ class AnnotationBorderStyle { * * @public * @memberof AnnotationBorderStyle - * @param {integer} radius - The horizontal corner radius + * @param {number} radius - The horizontal corner radius. */ setHorizontalCornerRadius(radius) { if (Number.isInteger(radius)) { @@ -655,7 +655,7 @@ class AnnotationBorderStyle { * * @public * @memberof AnnotationBorderStyle - * @param {integer} radius - The vertical corner radius + * @param {number} radius - The vertical corner radius. */ setVerticalCornerRadius(radius) { if (Number.isInteger(radius)) { diff --git a/src/core/colorspace.js b/src/core/colorspace.js index 11d420ac1..1c666acac 100644 --- a/src/core/colorspace.js +++ b/src/core/colorspace.js @@ -22,11 +22,11 @@ import { isDict, isName, isStream } from './primitives'; * Resizes an RGB image with 3 components. * @param {TypedArray} src - The source buffer. * @param {TypedArray} dest - The destination buffer. - * @param {Number} w1 - Original width. - * @param {Number} h1 - Original height. - * @param {Number} w2 - New width. - * @param {Number} h2 - New height. - * @param {Number} alpha01 - Size reserved for the alpha channel. + * @param {number} w1 - Original width. + * @param {number} h1 - Original height. + * @param {number} w2 - New width. + * @param {number} h2 - New height. + * @param {number} alpha01 - Size reserved for the alpha channel. */ function resizeRgbImage(src, dest, w1, h1, w2, h2, alpha01) { const COMPONENTS = 3; @@ -390,7 +390,7 @@ class ColorSpace { * This does not handle Lab, Indexed, or Pattern decode maps since they are * slightly different. * @param {Array} decode - Decode map (usually from an image). - * @param {Number} numComps - Number of components the color space has. + * @param {number} numComps - Number of components the color space has. */ static isDefaultDecode(decode, numComps) { if (!Array.isArray(decode)) { diff --git a/src/core/core_utils.js b/src/core/core_utils.js index 9d1bf124a..694342fa9 100644 --- a/src/core/core_utils.js +++ b/src/core/core_utils.js @@ -95,7 +95,7 @@ const ROMAN_NUMBER_MAP = [ /** * Converts positive integers to (upper case) Roman numerals. - * @param {integer} number - The number that should be converted. + * @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. diff --git a/src/core/image.js b/src/core/image.js index 2e848b25c..e448695e6 100644 --- a/src/core/image.js +++ b/src/core/image.js @@ -49,11 +49,11 @@ var PDFImage = (function PDFImageClosure() { /** * Resizes an image mask with 1 component. * @param {TypedArray} src - The source buffer. - * @param {Number} bpc - Number of bits per component. - * @param {Number} w1 - Original width. - * @param {Number} h1 - Original height. - * @param {Number} w2 - New width. - * @param {Number} h2 - New height. + * @param {number} bpc - Number of bits per component. + * @param {number} w1 - Original width. + * @param {number} h1 - Original height. + * @param {number} w2 - New width. + * @param {number} h2 - New height. * @returns {TypedArray} The resized image mask buffer. */ function resizeImageMask(src, bpc, w1, h1, w2, h2) { diff --git a/web/ui_utils.js b/web/ui_utils.js index cb7108a75..941db2383 100644 --- a/web/ui_utils.js +++ b/web/ui_utils.js @@ -215,7 +215,7 @@ function parseQueryString(query) { * that if the condition is true for one item in the array, then it is also true * for all following items. * - * @returns {Number} Index of the first array element to pass the test, + * @returns {number} Index of the first array element to pass the test, * or |items.length| if no such element exists. */ function binarySearchFirstItem(items, condition) { From efd331daa18a70e37ad52d2053a0e7c0a44d9737 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 15:59:09 +0200 Subject: [PATCH 2/9] Consistently use `string` for string data types in JSDoc comments Sometimes we also used `String`, but `string` is the what the JSDoc documentation recommends. --- extensions/chromium/pdfHandler-vcros.js | 2 +- src/shared/message_handler.js | 6 +++--- web/app.js | 2 +- web/chromecom.js | 6 +++--- web/firefoxcom.js | 8 ++++---- web/pdf_link_service.js | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/extensions/chromium/pdfHandler-vcros.js b/extensions/chromium/pdfHandler-vcros.js index 8eb5daa57..166b86312 100644 --- a/extensions/chromium/pdfHandler-vcros.js +++ b/extensions/chromium/pdfHandler-vcros.js @@ -28,7 +28,7 @@ limitations under the License. /** * Invoked when "Open with PDF Viewer" is chosen in the File browser. * - * @param {String} id File browser action ID as specified in + * @param {string} id File browser action ID as specified in * manifest.json * @param {Object} details Object of type FileHandlerExecuteEventDetails */ diff --git a/src/shared/message_handler.js b/src/shared/message_handler.js index 2a3178255..869a4a92f 100644 --- a/src/shared/message_handler.js +++ b/src/shared/message_handler.js @@ -132,7 +132,7 @@ MessageHandler.prototype = { }, /** * Sends a message to the comObj to invoke the action with the supplied data. - * @param {String} actionName - Action to call. + * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. * @param {Array} [transfers] - Optional list of transfers/ArrayBuffers */ @@ -147,7 +147,7 @@ MessageHandler.prototype = { /** * Sends a message to the comObj to invoke the action with the supplied data. * Expects that the other side will callback with the response. - * @param {String} actionName - Action to call. + * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. * @param {Array} [transfers] - Optional list of transfers/ArrayBuffers. * @returns {Promise} Promise to be resolved with response data. @@ -172,7 +172,7 @@ MessageHandler.prototype = { /** * Sends a message to the comObj to invoke the action with the supplied data. * Expect that the other side will callback to signal 'start_complete'. - * @param {String} actionName - Action to call. + * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. * @param {Object} queueingStrategy - strategy to signal backpressure based on * internal queue. diff --git a/web/app.js b/web/app.js index 35df745d2..f8ca4d2ae 100644 --- a/web/app.js +++ b/web/app.js @@ -764,7 +764,7 @@ let PDFViewerApplication = { /** * Show the error box. - * @param {String} message A message that is human readable. + * @param {string} message A message that is human readable. * @param {Object} moreInfo (optional) Further information about the error * that is more technical. Should have a 'message' * and optionally a 'stack' property. diff --git a/web/chromecom.js b/web/chromecom.js index 90819e406..9b461e65d 100644 --- a/web/chromecom.js +++ b/web/chromecom.js @@ -30,8 +30,8 @@ let ChromeCom = { * Creates an event that the extension is listening for and will * asynchronously respond by calling the callback. * - * @param {String} action The action to trigger. - * @param {String} data Optional data to send. + * @param {string} action The action to trigger. + * @param {string} data Optional data to send. * @param {Function} callback Optional response callback that will be called * with one data argument. When the request cannot be handled, the callback * is immediately invoked with no arguments. @@ -56,7 +56,7 @@ let ChromeCom = { /** * Resolves a PDF file path and attempts to detects length. * - * @param {String} file - Absolute URL of PDF file. + * @param {string} file - Absolute URL of PDF file. * @param {OverlayManager} overlayManager - Manager for the viewer overlays. * @param {Function} callback - A callback with resolved URL and file length. */ diff --git a/web/firefoxcom.js b/web/firefoxcom.js index ee4bab647..e0af9fa12 100644 --- a/web/firefoxcom.js +++ b/web/firefoxcom.js @@ -32,8 +32,8 @@ let FirefoxCom = (function FirefoxComClosure() { * synchronously respond to. * NOTE: It is reccomended to use request() instead since one day we may not * be able to synchronously reply. - * @param {String} action The action to trigger. - * @param {String} data Optional data to send. + * @param {string} action The action to trigger. + * @param {string} data Optional data to send. * @return {*} The response. */ requestSync(action, data) { @@ -52,8 +52,8 @@ let FirefoxCom = (function FirefoxComClosure() { /** * Creates an event that the extension is listening for and will * asynchronously respond by calling the callback. - * @param {String} action The action to trigger. - * @param {String} data Optional data to send. + * @param {string} action The action to trigger. + * @param {string} data Optional data to send. * @param {Function} callback Optional response callback that will be called * with one data argument. */ diff --git a/web/pdf_link_service.js b/web/pdf_link_service.js index c19257e15..42bfb9f99 100644 --- a/web/pdf_link_service.js +++ b/web/pdf_link_service.js @@ -189,7 +189,7 @@ class PDFLinkService { /** * Prefix the full url on anchor links to make sure that links are resolved * relative to the current URL instead of the one defined in . - * @param {String} anchor The anchor hash, including the #. + * @param {string} anchor The anchor hash, including the #. * @returns {string} The hyperlink to the PDF object. */ getAnchorUrl(anchor) { From f4daafc0775715392cbae45ca7f5df0c6ecc3481 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 16:30:32 +0200 Subject: [PATCH 3/9] Consistently use square brackets for optional parameters in JSDoc comments Square brackets are recommended to indicate optional parameters. Using them helps for automatically generating correct documentation. --- src/core/ccitt.js | 2 +- src/core/obj.js | 4 +-- src/display/annotation_layer.js | 8 ++--- src/display/display_utils.js | 38 +++++++++++----------- src/display/text_layer.js | 25 +++++++-------- src/shared/message_handler.js | 8 ++--- web/annotation_layer_builder.js | 8 ++--- web/app.js | 14 ++++---- web/base_viewer.js | 57 ++++++++++++++++----------------- web/chromecom.js | 10 +++--- web/firefoxcom.js | 12 +++---- web/interfaces.js | 4 +-- web/overlay_manager.js | 14 ++++---- web/pdf_cursor_tools.js | 6 ++-- web/pdf_history.js | 10 +++--- web/pdf_link_service.js | 8 ++--- web/pdf_page_view.js | 22 ++++++------- web/pdf_presentation_mode.js | 6 ++-- web/pdf_sidebar.js | 8 ++--- web/pdf_thumbnail_view.js | 6 ++-- web/text_layer_builder.js | 4 +-- 21 files changed, 136 insertions(+), 138 deletions(-) diff --git a/src/core/ccitt.js b/src/core/ccitt.js index 2f9bb4fe0..3f81e339a 100644 --- a/src/core/ccitt.js +++ b/src/core/ccitt.js @@ -458,7 +458,7 @@ let CCITTFaxDecoder = (function CCITTFaxDecoder() { /** * @param {CCITTFaxDecoderSource} source - The data which should be decoded. - * @param {Object} options - (optional) Decoding options. + * @param {Object} [options] - Decoding options. */ function CCITTFaxDecoder(source, options = {}) { if (!source || typeof source.next !== 'function') { diff --git a/src/core/obj.js b/src/core/obj.js index 9b74c7b1b..e854e1e1f 100644 --- a/src/core/obj.js +++ b/src/core/obj.js @@ -863,8 +863,8 @@ class Catalog { * @property {Dict} destDict - The dictionary containing the destination. * @property {Object} resultObj - The object where the parsed destination * properties will be placed. - * @property {string} docBaseUrl - (optional) The document base URL that is - * used when attempting to recover valid absolute URLs from relative ones. + * @property {string} [docBaseUrl] - The document base URL that is used when + * attempting to recover valid absolute URLs from relative ones. */ /** diff --git a/src/display/annotation_layer.js b/src/display/annotation_layer.js index fdf06a62e..9bd3c08ee 100644 --- a/src/display/annotation_layer.js +++ b/src/display/annotation_layer.js @@ -31,8 +31,8 @@ import { * @property {PageViewport} viewport * @property {IPDFLinkService} linkService * @property {DownloadManager} downloadManager - * @property {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @property {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @property {boolean} renderInteractiveForms * @property {Object} svgFactory */ @@ -1328,8 +1328,8 @@ class FileAttachmentAnnotationElement extends AnnotationElement { * @property {PDFPage} page * @property {IPDFLinkService} linkService * @property {DownloadManager} downloadManager - * @property {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @property {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @property {boolean} renderInteractiveForms */ diff --git a/src/display/display_utils.js b/src/display/display_utils.js index e2c47b3cf..aa671c802 100644 --- a/src/display/display_utils.js +++ b/src/display/display_utils.js @@ -160,22 +160,22 @@ class DOMSVGFactory { * @property {Array} viewBox - The xMin, yMin, xMax and yMax coordinates. * @property {number} scale - The scale of the viewport. * @property {number} rotation - The rotation, in degrees, of the viewport. - * @property {number} offsetX - (optional) The horizontal, i.e. x-axis, offset. - * The default value is `0`. - * @property {number} offsetY - (optional) The vertical, i.e. y-axis, offset. - * The default value is `0`. - * @property {boolean} dontFlip - (optional) If true, the y-axis will not be - * flipped. The default value is `false`. + * @property {number} [offsetX] - The horizontal, i.e. x-axis, offset. The + * default value is `0`. + * @property {number} [offsetY] - The vertical, i.e. y-axis, offset. The + * default value is `0`. + * @property {boolean} [dontFlip] - If true, the y-axis will not be flipped. + * The default value is `false`. */ /** * @typedef {Object} PageViewportCloneParameters - * @property {number} scale - (optional) The scale, overriding the one in the - * cloned viewport. The default value is `this.scale`. - * @property {number} rotation - (optional) The rotation, in degrees, overriding - * the one in the cloned viewport. The default value is `this.rotation`. - * @property {boolean} dontFlip - (optional) If true, the x-axis will not be - * flipped. The default value is `false`. + * @property {number} [scale] - The scale, overriding the one in the cloned + * viewport. The default value is `this.scale`. + * @property {number} [rotation] - The rotation, in degrees, overriding the one + * in the cloned viewport. The default value is `this.rotation`. + * @property {boolean} [dontFlip] - If true, the x-axis will not be flipped. + * The default value is `false`. */ /** @@ -251,7 +251,7 @@ class PageViewport { /** * Clones viewport, with optional additional properties. - * @param {PageViewportCloneParameters} - (optional) + * @param {PageViewportCloneParameters} [params] * @return {PageViewport} Cloned viewport. */ clone({ scale = this.scale, rotation = this.rotation, @@ -334,12 +334,12 @@ const LinkTargetStringMap = [ * @typedef ExternalLinkParameters * @typedef {Object} ExternalLinkParameters * @property {string} url - An absolute URL. - * @property {LinkTarget} target - (optional) The link target. - * The default value is `LinkTarget.NONE`. - * @property {string} rel - (optional) The link relationship. - * The default value is `DEFAULT_LINK_REL`. - * @property {boolean} enabled - (optional) Whether the link should be enabled. - * The default value is true. + * @property {LinkTarget} [target] - The link target. The default value is + * `LinkTarget.NONE`. + * @property {string} [rel] - The link relationship. The default value is + * `DEFAULT_LINK_REL`. + * @property {boolean} [enabled] - Whether the link should be enabled. The + * default value is true. */ /** diff --git a/src/display/text_layer.js b/src/display/text_layer.js index 1bd06bfd5..d900d2d32 100644 --- a/src/display/text_layer.js +++ b/src/display/text_layer.js @@ -20,24 +20,23 @@ import globalScope from '../shared/global_scope'; * Text layer render parameters. * * @typedef {Object} TextLayerRenderParameters - * @property {TextContent} textContent - (optional) Text content to render - * (the object is returned by the page's getTextContent() method). - * @property {ReadableStream} textContentStream - (optional) Text content - * stream to render (the stream is returned by the page's - * streamTextContent() method). + * @property {TextContent} [textContent] - Text content to render (the object + * is returned by the page's `getTextContent` method). + * @property {ReadableStream} [textContentStream] - Text content stream to + * render (the stream is returned by the page's `streamTextContent` method). * @property {HTMLElement} container - HTML element that will contain text runs. * @property {PageViewport} viewport - The target viewport to properly * layout the text runs. - * @property {Array} textDivs - (optional) HTML elements that are correspond - * the text items of the textContent input. This is output and shall be + * @property {Array} [textDivs] - HTML elements that are correspond to the + * text items of the textContent input. This is output and shall be * initially be set to empty array. - * @property {Array} textContentItemsStr - (optional) Strings that correspond - * the `str` property of the text items of textContent input. This is output + * @property {Array} [textContentItemsStr] - Strings that correspond to the + * `str` property of the text items of textContent input. This is output * and shall be initially be set to empty array. - * @property {number} timeout - (optional) Delay in milliseconds before - * rendering of the text runs occurs. - * @property {boolean} enhanceTextSelection - (optional) Whether to turn on the - * text selection enhancement. + * @property {number} [timeout] - Delay in milliseconds before rendering of the + * text runs occurs. + * @property {boolean} [enhanceTextSelection] - Whether to turn on the text + * selection enhancement. */ var renderTextLayer = (function renderTextLayerClosure() { var MAX_TEXT_DIVS_TO_RENDER = 100000; diff --git a/src/shared/message_handler.js b/src/shared/message_handler.js index 869a4a92f..bed45e28a 100644 --- a/src/shared/message_handler.js +++ b/src/shared/message_handler.js @@ -134,7 +134,7 @@ MessageHandler.prototype = { * Sends a message to the comObj to invoke the action with the supplied data. * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. - * @param {Array} [transfers] - Optional list of transfers/ArrayBuffers + * @param {Array} [transfers] - List of transfers/ArrayBuffers. */ send(actionName, data, transfers) { this.postMessage({ @@ -149,7 +149,7 @@ MessageHandler.prototype = { * Expects that the other side will callback with the response. * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. - * @param {Array} [transfers] - Optional list of transfers/ArrayBuffers. + * @param {Array} [transfers] - List of transfers/ArrayBuffers. * @returns {Promise} Promise to be resolved with response data. */ sendWithPromise(actionName, data, transfers) { @@ -174,9 +174,9 @@ MessageHandler.prototype = { * Expect that the other side will callback to signal 'start_complete'. * @param {string} actionName - Action to call. * @param {JSON} data - JSON data to send. - * @param {Object} queueingStrategy - strategy to signal backpressure based on + * @param {Object} queueingStrategy - Strategy to signal backpressure based on * internal queue. - * @param {Array} [transfers] - Optional list of transfers/ArrayBuffers. + * @param {Array} [transfers] - List of transfers/ArrayBuffers. * @return {ReadableStream} ReadableStream to read data in chunks. */ sendWithStream(actionName, data, queueingStrategy, transfers) { diff --git a/web/annotation_layer_builder.js b/web/annotation_layer_builder.js index 10f1eeec0..9805c2e29 100644 --- a/web/annotation_layer_builder.js +++ b/web/annotation_layer_builder.js @@ -21,8 +21,8 @@ import { SimpleLinkService } from './pdf_link_service'; * @typedef {Object} AnnotationLayerBuilderOptions * @property {HTMLDivElement} pageDiv * @property {PDFPage} pdfPage - * @property {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @property {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @property {boolean} renderInteractiveForms * @property {IPDFLinkService} linkService * @property {DownloadManager} downloadManager @@ -109,8 +109,8 @@ class DefaultAnnotationLayerFactory { /** * @param {HTMLDivElement} pageDiv * @param {PDFPage} pdfPage - * @param {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @param {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @param {boolean} renderInteractiveForms * @param {IL10n} l10n * @returns {AnnotationLayerBuilder} diff --git a/web/app.js b/web/app.js index f8ca4d2ae..a0390ca15 100644 --- a/web/app.js +++ b/web/app.js @@ -609,9 +609,9 @@ let PDFViewerApplication = { /** * Opens PDF document specified by URL or array with additional arguments. * @param {string|TypedArray|ArrayBuffer} file - PDF location or binary data. - * @param {Object} args - (optional) Additional arguments for the getDocument - * call, e.g. HTTP headers ('httpHeaders') or - * alternative data transport ('range'). + * @param {Object} [args] - Additional arguments for the getDocument call, + * e.g. HTTP headers ('httpHeaders') or alternative + * data transport ('range'). * @returns {Promise} - Returns the promise, which is resolved when document * is opened. */ @@ -764,10 +764,10 @@ let PDFViewerApplication = { /** * Show the error box. - * @param {string} message A message that is human readable. - * @param {Object} moreInfo (optional) Further information about the error - * that is more technical. Should have a 'message' - * and optionally a 'stack' property. + * @param {string} message - A message that is human readable. + * @param {Object} [moreInfo] - Further information about the error that is + * more technical. Should have a 'message' and + * optionally a 'stack' property. */ error(message, moreInfo) { let moreInfoText = [this.l10n.get('error_version_info', diff --git a/web/base_viewer.js b/web/base_viewer.js index ff10255d9..d7675e5c8 100644 --- a/web/base_viewer.js +++ b/web/base_viewer.js @@ -33,36 +33,35 @@ const DEFAULT_CACHE_SIZE = 10; /** * @typedef {Object} PDFViewerOptions * @property {HTMLDivElement} container - The container for the viewer element. - * @property {HTMLDivElement} viewer - (optional) The viewer element. + * @property {HTMLDivElement} [viewer] - The viewer element. * @property {EventBus} eventBus - The application event bus. * @property {IPDFLinkService} linkService - The navigation/linking service. - * @property {DownloadManager} downloadManager - (optional) The download - * manager component. - * @property {PDFFindController} findController - (optional) The find - * controller component. - * @property {PDFRenderingQueue} renderingQueue - (optional) The rendering - * queue object. - * @property {boolean} removePageBorders - (optional) Removes the border shadow - * around the pages. The default value is `false`. - * @property {number} textLayerMode - (optional) Controls if the text layer used - * for selection and searching is created, and if the improved text selection + * @property {DownloadManager} [downloadManager] - The download manager + * component. + * @property {PDFFindController} [findController] - The find controller + * component. + * @property {PDFRenderingQueue} [renderingQueue] - The rendering queue object. + * @property {boolean} [removePageBorders] - Removes the border shadow around + * the pages. The default value is `false`. + * @property {number} [textLayerMode] - Controls if the text layer used for + * selection and searching is created, and if the improved text selection * behaviour is enabled. The constants from {TextLayerMode} should be used. * The default value is `TextLayerMode.ENABLE`. - * @property {string} imageResourcesPath - (optional) Path for image resources, + * @property {string} [imageResourcesPath] - Path for image resources, mainly * mainly for annotation icons. Include trailing slash. - * @property {boolean} renderInteractiveForms - (optional) Enables rendering of + * @property {boolean} [renderInteractiveForms] - Enables rendering of * interactive form elements. The default is `false`. - * @property {boolean} enablePrintAutoRotate - (optional) Enables automatic - * rotation of pages whose orientation differ from the first page upon - * printing. The default is `false`. + * @property {boolean} [enablePrintAutoRotate] - Enables automatic rotation of + * pages whose orientation differ from the first page upon printing. The + * default is `false`. * @property {string} renderer - 'canvas' or 'svg'. The default is 'canvas'. - * @property {boolean} enableWebGL - (optional) Enables WebGL accelerated - * rendering for some operations. The default value is `false`. - * @property {boolean} useOnlyCssZoom - (optional) Enables CSS only zooming. - * The default value is `false`. - * @property {number} maxCanvasPixels - (optional) The maximum supported canvas - * size in total pixels, i.e. width * height. Use -1 for no limit. - * The default value is 4096 * 4096 (16 mega-pixels). + * @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering for + * some operations. The default value is `false`. + * @property {boolean} [useOnlyCssZoom] - Enables CSS only zooming. The default + * value is `false`. + * @property {number} [maxCanvasPixels] - The maximum supported canvas size in + * total pixels, i.e. width * height. Use -1 for no limit. The default value + * is 4096 * 4096 (16 mega-pixels). * @property {IL10n} l10n - Localization service. */ @@ -666,10 +665,10 @@ class BaseViewer { /** * @typedef ScrollPageIntoViewParameters * @property {number} pageNumber - The page number. - * @property {Array} destArray - (optional) The original PDF destination - * array, in the format: - * @property {boolean} allowNegativeOffset - (optional) Allow negative page - * offsets. The default value is `false`. + * @property {Array} [destArray] - The original PDF destination array, in the + * format: + * @property {boolean} [allowNegativeOffset] - Allow negative page offsets. + * The default value is `false`. */ /** @@ -1009,8 +1008,8 @@ class BaseViewer { /** * @param {HTMLDivElement} pageDiv * @param {PDFPage} pdfPage - * @param {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @param {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @param {boolean} renderInteractiveForms * @param {IL10n} l10n * @returns {AnnotationLayerBuilder} diff --git a/web/chromecom.js b/web/chromecom.js index 9b461e65d..96d84a200 100644 --- a/web/chromecom.js +++ b/web/chromecom.js @@ -30,11 +30,11 @@ let ChromeCom = { * Creates an event that the extension is listening for and will * asynchronously respond by calling the callback. * - * @param {string} action The action to trigger. - * @param {string} data Optional data to send. - * @param {Function} callback Optional response callback that will be called - * with one data argument. When the request cannot be handled, the callback - * is immediately invoked with no arguments. + * @param {string} action - The action to trigger. + * @param {string} [data] - The data to send. + * @param {Function} [callback] - Response callback that will be called with + * one data argument. When the request cannot be handled, the callback is + * immediately invoked with no arguments. */ request(action, data, callback) { let message = { diff --git a/web/firefoxcom.js b/web/firefoxcom.js index e0af9fa12..05d31420f 100644 --- a/web/firefoxcom.js +++ b/web/firefoxcom.js @@ -32,8 +32,8 @@ let FirefoxCom = (function FirefoxComClosure() { * synchronously respond to. * NOTE: It is reccomended to use request() instead since one day we may not * be able to synchronously reply. - * @param {string} action The action to trigger. - * @param {string} data Optional data to send. + * @param {string} action - The action to trigger. + * @param {string} [data] - The data to send. * @return {*} The response. */ requestSync(action, data) { @@ -52,10 +52,10 @@ let FirefoxCom = (function FirefoxComClosure() { /** * Creates an event that the extension is listening for and will * asynchronously respond by calling the callback. - * @param {string} action The action to trigger. - * @param {string} data Optional data to send. - * @param {Function} callback Optional response callback that will be called - * with one data argument. + * @param {string} action - The action to trigger. + * @param {string} [data] - The data to send. + * @param {Function} [callback] - Response callback that will be called + * with one data argument. */ request(action, data, callback) { let request = document.createTextNode(''); diff --git a/web/interfaces.js b/web/interfaces.js index bb22e0bed..a8780f9ba 100644 --- a/web/interfaces.js +++ b/web/interfaces.js @@ -156,8 +156,8 @@ class IPDFAnnotationLayerFactory { /** * @param {HTMLDivElement} pageDiv * @param {PDFPage} pdfPage - * @param {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @param {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @param {boolean} renderInteractiveForms * @param {IL10n} l10n * @returns {AnnotationLayerBuilder} diff --git a/web/overlay_manager.js b/web/overlay_manager.js index 461244076..2a7688f99 100644 --- a/web/overlay_manager.js +++ b/web/overlay_manager.js @@ -27,13 +27,13 @@ class OverlayManager { /** * @param {string} name - The name of the overlay that is registered. * @param {HTMLDivElement} element - The overlay's DOM element. - * @param {function} callerCloseMethod - (optional) The method that, if - * present, calls `OverlayManager.close` from the object - * registering the overlay. Access to this method is - * necessary in order to run cleanup code when e.g. - * the overlay is force closed. The default is `null`. - * @param {boolean} canForceClose - (optional) Indicates if opening the - * overlay closes an active overlay. The default is `false`. + * @param {function} [callerCloseMethod] - The method that, if present, calls + * `OverlayManager.close` from the object registering the + * overlay. Access to this method is necessary in order to + * run cleanup code when e.g. the overlay is force closed. + * The default is `null`. + * @param {boolean} [canForceClose] - Indicates if opening the overlay closes + * an active overlay. The default is `false`. * @returns {Promise} A promise that is resolved when the overlay has been * registered. */ diff --git a/web/pdf_cursor_tools.js b/web/pdf_cursor_tools.js index 252963944..d7965aca0 100644 --- a/web/pdf_cursor_tools.js +++ b/web/pdf_cursor_tools.js @@ -25,9 +25,9 @@ const CursorTool = { * @typedef {Object} PDFCursorToolsOptions * @property {HTMLDivElement} container - The document container. * @property {EventBus} eventBus - The application event bus. - * @property {number} cursorToolOnLoad - (optional) The cursor tool that will be - * enabled on load; the constants from {CursorTool} should be used. - * The default value is `CursorTool.SELECT`. + * @property {number} [cursorToolOnLoad] - The cursor tool that will be enabled + * on load; the constants from {CursorTool} should be used. The default value + * is `CursorTool.SELECT`. */ class PDFCursorTools { diff --git a/web/pdf_history.js b/web/pdf_history.js index c94aa3b19..74042ba39 100644 --- a/web/pdf_history.js +++ b/web/pdf_history.js @@ -33,15 +33,15 @@ const UPDATE_VIEWAREA_TIMEOUT = 1000; // milliseconds /** * @typedef {Object} InitializeParameters * @property {string} fingerprint - The PDF document's unique fingerprint. - * @property {boolean} resetHistory - (optional) Reset the browsing history. - * @property {boolean} updateUrl - (optional) Attempt to update the document - * URL, with the current hash, when pushing/replacing browser history entries. + * @property {boolean} [resetHistory] - Reset the browsing history. + * @property {boolean} [updateUrl] - Attempt to update the document URL, with + * the current hash, when pushing/replacing browser history entries. */ /** * @typedef {Object} PushParameters - * @property {string} namedDest - (optional) The named destination. If absent, - * a stringified version of `explicitDest` is used. + * @property {string} [namedDest] - The named destination. If absent, a + * stringified version of `explicitDest` is used. * @property {Array} explicitDest - The explicit destination array. * @property {number} pageNumber - The page to which the destination points. */ diff --git a/web/pdf_link_service.js b/web/pdf_link_service.js index 42bfb9f99..a34c4fe71 100644 --- a/web/pdf_link_service.js +++ b/web/pdf_link_service.js @@ -18,11 +18,11 @@ import { getGlobalEventBus, parseQueryString } from './ui_utils'; /** * @typedef {Object} PDFLinkServiceOptions * @property {EventBus} eventBus - The application event bus. - * @property {number} externalLinkTarget - (optional) Specifies the `target` - * attribute for external links. Must use one of the values from {LinkTarget}. + * @property {number} [externalLinkTarget] - Specifies the `target` attribute + * for external links. Must use one of the values from {LinkTarget}. * Defaults to using no target. - * @property {string} externalLinkRel - (optional) Specifies the `rel` attribute - * for external links. Defaults to stripping the referrer. + * @property {string} [externalLinkRel] - Specifies the `rel` attribute for + * external links. Defaults to stripping the referrer. */ /** diff --git a/web/pdf_page_view.js b/web/pdf_page_view.js index 8f13a608d..c1bdef65e 100644 --- a/web/pdf_page_view.js +++ b/web/pdf_page_view.js @@ -32,23 +32,23 @@ import { viewerCompatibilityParams } from './viewer_compatibility'; * @property {PageViewport} defaultViewport - The page viewport. * @property {PDFRenderingQueue} renderingQueue - The rendering queue object. * @property {IPDFTextLayerFactory} textLayerFactory - * @property {number} textLayerMode - (optional) Controls if the text layer used - * for selection and searching is created, and if the improved text selection + * @property {number} [textLayerMode] - Controls if the text layer used for + * selection and searching is created, and if the improved text selection * behaviour is enabled. The constants from {TextLayerMode} should be used. * The default value is `TextLayerMode.ENABLE`. * @property {IPDFAnnotationLayerFactory} annotationLayerFactory - * @property {string} imageResourcesPath - (optional) Path for image resources, - * mainly for annotation icons. Include trailing slash. + * @property {string} [imageResourcesPath] - Path for image resources, mainly + * for annotation icons. Include trailing slash. * @property {boolean} renderInteractiveForms - Turns on rendering of * interactive form elements. The default is `false`. * @property {string} renderer - 'canvas' or 'svg'. The default is 'canvas'. - * @property {boolean} enableWebGL - (optional) Enables WebGL accelerated - * rendering for some operations. The default value is `false`. - * @property {boolean} useOnlyCssZoom - (optional) Enables CSS only zooming. - * The default value is `false`. - * @property {number} maxCanvasPixels - (optional) The maximum supported canvas - * size in total pixels, i.e. width * height. Use -1 for no limit. - * The default value is 4096 * 4096 (16 mega-pixels). + * @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering for + * some operations. The default value is `false`. + * @property {boolean} [useOnlyCssZoom] - Enables CSS only zooming. The default + * value is `false`. + * @property {number} [maxCanvasPixels] - The maximum supported canvas size in + * total pixels, i.e. width * height. Use -1 for no limit. The default value + * is 4096 * 4096 (16 mega-pixels). * @property {IL10n} l10n - Localization service. */ diff --git a/web/pdf_presentation_mode.js b/web/pdf_presentation_mode.js index 93eedb2bf..bea6a3a13 100644 --- a/web/pdf_presentation_mode.js +++ b/web/pdf_presentation_mode.js @@ -32,11 +32,11 @@ const SWIPE_ANGLE_THRESHOLD = Math.PI / 6; /** * @typedef {Object} PDFPresentationModeOptions * @property {HTMLDivElement} container - The container for the viewer element. - * @property {HTMLDivElement} viewer - (optional) The viewer element. + * @property {HTMLDivElement} [viewer] - The viewer element. * @property {PDFViewer} pdfViewer - The document viewer. * @property {EventBus} eventBus - The application event bus. - * @property {Array} contextMenuItems - (optional) The menu items that are added - * to the context menu in Presentation Mode. + * @property {Array} [contextMenuItems] - The menu items that are added to the + * context menu in Presentation Mode. */ class PDFPresentationMode { diff --git a/web/pdf_sidebar.js b/web/pdf_sidebar.js index 5b39cf5bf..3cb72907d 100644 --- a/web/pdf_sidebar.js +++ b/web/pdf_sidebar.js @@ -34,8 +34,8 @@ const SidebarView = { * @property {PDFThumbnailViewer} pdfThumbnailViewer - The thumbnail viewer. * @property {EventBus} eventBus - The application event bus. * @property {IL10n} l10n - The localization service. - * @property {boolean} disableNotification - (optional) Disable the notification - * for documents containing outline/attachments. The default value is `false`. + * @property {boolean} [disableNotification] - Disable the notification for + * documents containing outline/attachments. The default value is `false`. */ /** @@ -153,8 +153,8 @@ class PDFSidebar { /** * @param {number} view - The sidebar view that should be switched to, * must be one of the values in {SidebarView}. - * @param {boolean} forceOpen - (optional) Ensure that the sidebar is open. - * The default value is `false`. + * @param {boolean} [forceOpen] - Ensure that the sidebar is open. + * The default value is `false`. */ switchView(view, forceOpen = false) { this._switchView(view, forceOpen); diff --git a/web/pdf_thumbnail_view.js b/web/pdf_thumbnail_view.js index 601ecad7a..6f7c8b486 100644 --- a/web/pdf_thumbnail_view.js +++ b/web/pdf_thumbnail_view.js @@ -30,9 +30,9 @@ const THUMBNAIL_WIDTH = 98; // px * @property {PageViewport} defaultViewport - The page viewport. * @property {IPDFLinkService} linkService - The navigation/linking service. * @property {PDFRenderingQueue} renderingQueue - The rendering queue object. - * @property {boolean} disableCanvasToImageConversion - (optional) Don't convert - * the canvas thumbnails to images. This prevents `toDataURL` calls, - * but increases the overall memory usage. The default value is `false`. + * @property {boolean} [disableCanvasToImageConversion] - Don't convert the + * canvas thumbnails to images. This prevents `toDataURL` calls, but + * increases the overall memory usage. The default value is `false`. * @property {IL10n} l10n - Localization service. */ diff --git a/web/text_layer_builder.js b/web/text_layer_builder.js index 6a59e5527..096b3f120 100644 --- a/web/text_layer_builder.js +++ b/web/text_layer_builder.js @@ -79,8 +79,8 @@ class TextLayerBuilder { /** * Renders the text layer. * - * @param {number} timeout - (optional) wait for a specified amount of - * milliseconds before rendering + * @param {number} [timeout] - Wait for a specified amount of milliseconds + * before rendering. */ render(timeout = 0) { if (!(this.textContent || this.textContentStream) || this.renderingDone) { From 8b4ae6f3eb7c6c9e54b8542d1588e5e49ee3e0b3 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 17:02:54 +0200 Subject: [PATCH 4/9] Consistently use `@type` for getter data types in JSDoc comments Sometimes we also used `@return` or `@returns`, but `@type` is what the JSDoc documentation recommends. This also improves the documentation because before this commit the types were not shown and now they are. --- src/core/annotation.js | 4 ++-- src/core/operator_list.js | 4 ++-- src/display/api.js | 32 ++++++++++++++++---------------- src/interfaces.js | 14 +++++++------- web/base_viewer.js | 22 +++++++++++----------- web/interfaces.js | 12 ++++++------ web/pdf_cursor_tools.js | 2 +- web/pdf_find_controller.js | 2 +- web/pdf_history.js | 2 +- web/pdf_link_service.js | 12 ++++++------ web/pdf_sidebar.js | 2 +- web/pdf_sidebar_resizer.js | 2 +- web/secondary_toolbar.js | 2 +- 13 files changed, 56 insertions(+), 56 deletions(-) diff --git a/src/core/annotation.js b/src/core/annotation.js index fbfd88056..156bf1ab2 100644 --- a/src/core/annotation.js +++ b/src/core/annotation.js @@ -253,7 +253,7 @@ class Annotation { } /** - * @return {boolean} + * @type {boolean} */ get viewable() { if (this.flags === 0) { @@ -263,7 +263,7 @@ class Annotation { } /** - * @return {boolean} + * @type {boolean} */ get printable() { if (this.flags === 0) { diff --git a/src/core/operator_list.js b/src/core/operator_list.js index 703a495d6..d54f30492 100644 --- a/src/core/operator_list.js +++ b/src/core/operator_list.js @@ -568,8 +568,8 @@ var OperatorList = (function OperatorListClosure() { }, /** - * @returns {number} The total length of the entire operator list, - * since `this.length === 0` after flushing. + * @type {number} The total length of the entire operator list, since + * `this.length === 0` after flushing. */ get totalLength() { return (this._totalLength + this.length); diff --git a/src/display/api.js b/src/display/api.js index bfdb24484..52f4cbfc7 100644 --- a/src/display/api.js +++ b/src/display/api.js @@ -467,7 +467,7 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() { /** * Promise for document loading task completion. - * @return {Promise} + * @type {Promise} */ get promise() { return this._capability.promise; @@ -591,14 +591,14 @@ class PDFDocumentProxy { } /** - * @return {number} Total number of pages the PDF contains. + * @type {number} Total number of pages the PDF contains. */ get numPages() { return this._pdfInfo.numPages; } /** - * @return {string} A (not guaranteed to be) unique ID to identify a PDF. + * @type {string} A (not guaranteed to be) unique ID to identify a PDF. */ get fingerprint() { return this._pdfInfo.fingerprint; @@ -780,16 +780,16 @@ class PDFDocumentProxy { } /** - * @return {Object} A subset of the current {DocumentInitParameters}, - * which are either needed in the viewer and/or whose default values - * may be affected by the `apiCompatibilityParams`. + * @type {Object} A subset of the current {DocumentInitParameters}, which are + * either needed in the viewer and/or whose default values may be affected + * by the `apiCompatibilityParams`. */ get loadingParams() { return this._transport.loadingParams; } /** - * @return {PDFDocumentLoadingTask} The loadingTask for the current document. + * @type {PDFDocumentLoadingTask} The loadingTask for the current document. */ get loadingTask() { return this._transport.loadingTask; @@ -915,37 +915,37 @@ class PDFPageProxy { } /** - * @return {number} Page number of the page. First page is 1. + * @type {number} Page number of the page. First page is 1. */ get pageNumber() { return this.pageIndex + 1; } /** - * @return {number} The number of degrees the page is rotated clockwise. + * @type {number} The number of degrees the page is rotated clockwise. */ get rotate() { return this._pageInfo.rotate; } /** - * @return {Object} The reference that points to this page. It has 'num' and - * 'gen' properties. + * @type {Object} The reference that points to this page. It has `num` and + * `gen` properties. */ get ref() { return this._pageInfo.ref; } /** - * @return {number} The default size of units in 1/72nds of an inch. + * @type {number} The default size of units in 1/72nds of an inch. */ get userUnit() { return this._pageInfo.userUnit; } /** - * @return {Array} An array of the visible portion of the PDF page in the - * user space units - [x1, y1, x2, y2]. + * @type {Array} An array of the visible portion of the PDF page in user + * space units [x1, y1, x2, y2]. */ get view() { return this._pageInfo.view; @@ -1406,7 +1406,7 @@ class PDFPageProxy { } /** - * @return {Object} Returns page stats, if enabled. + * @type {Object} Returns page stats, if enabled. */ get stats() { return (this._stats instanceof StatTimer ? this._stats : null); @@ -2521,7 +2521,7 @@ class RenderTask { /** * Promise for rendering task completion. - * @return {Promise} + * @type {Promise} */ get promise() { return this._internalRenderTask.capability.promise; diff --git a/src/interfaces.js b/src/interfaces.js index e83991685..556577508 100644 --- a/src/interfaces.js +++ b/src/interfaces.js @@ -64,7 +64,7 @@ class IPDFStreamReader { /** * Gets a promise that is resolved when the headers and other metadata of * the PDF data stream are available. - * @returns {Promise} + * @type {Promise} */ get headersReady() { return Promise.resolve(); @@ -73,8 +73,8 @@ class IPDFStreamReader { /** * Gets the Content-Disposition filename. It is defined after the headersReady * promise is resolved. - * @returns {string|null} The filename, or `null` if the Content-Disposition - * header is missing/invalid. + * @type {string|null} The filename, or `null` if the Content-Disposition + * header is missing/invalid. */ get filename() { return null; @@ -83,7 +83,7 @@ class IPDFStreamReader { /** * Gets PDF binary data length. It is defined after the headersReady promise * is resolved. - * @returns {number} The data length (or 0 if unknown). + * @type {number} The data length (or 0 if unknown). */ get contentLength() { return 0; @@ -93,7 +93,7 @@ class IPDFStreamReader { * Gets ability of the stream to handle range requests. It is defined after * the headersReady promise is resolved. Rejected when the reader is cancelled * or an error occurs. - * @returns {boolean} + * @type {boolean} */ get isRangeSupported() { return false; @@ -102,7 +102,7 @@ class IPDFStreamReader { /** * Gets ability of the stream to progressively load binary data. It is defined * after the headersReady promise is resolved. - * @returns {boolean} + * @type {boolean} */ get isStreamingSupported() { return false; @@ -143,7 +143,7 @@ class IPDFStreamRangeReader { /** * Gets ability of the stream to progressively load binary data. - * @returns {boolean} + * @type {boolean} */ get isStreamingSupported() { return false; diff --git a/web/base_viewer.js b/web/base_viewer.js index d7675e5c8..be5b71e62 100644 --- a/web/base_viewer.js +++ b/web/base_viewer.js @@ -178,14 +178,14 @@ class BaseViewer { } /** - * @returns {boolean} true if all {PDFPageView} objects are initialized. + * @type {boolean} - True if all {PDFPageView} objects are initialized. */ get pageViewsReady() { return this._pageViewsReady; } /** - * @returns {number} + * @type {number} */ get currentPageNumber() { return this._currentPageNumber; @@ -238,8 +238,8 @@ class BaseViewer { } /** - * @returns {string|null} Returns the current page label, - * or `null` if no page labels exist. + * @type {string|null} Returns the current page label, or `null` if no page + * labels exist. */ get currentPageLabel() { return this._pageLabels && this._pageLabels[this._currentPageNumber - 1]; @@ -267,7 +267,7 @@ class BaseViewer { } /** - * @returns {number} + * @type {number} */ get currentScale() { return this._currentScale !== UNKNOWN_SCALE ? this._currentScale : @@ -288,7 +288,7 @@ class BaseViewer { } /** - * @returns {string} + * @type {string} */ get currentScaleValue() { return this._currentScaleValue; @@ -305,7 +305,7 @@ class BaseViewer { } /** - * @returns {number} + * @type {number} */ get pagesRotation() { return this._pagesRotation; @@ -1029,8 +1029,8 @@ class BaseViewer { } /** - * @returns {boolean} Whether all pages of the PDF document have identical - * widths and heights. + * @type {boolean} Whether all pages of the PDF document have identical + * widths and heights. */ get hasEqualPageSizes() { let firstPageView = this._pages[0]; @@ -1074,7 +1074,7 @@ class BaseViewer { } /** - * @return {number} One of the values in {ScrollMode}. + * @type {number} One of the values in {ScrollMode}. */ get scrollMode() { return this._scrollMode; @@ -1120,7 +1120,7 @@ class BaseViewer { } /** - * @return {number} One of the values in {SpreadMode}. + * @type {number} One of the values in {SpreadMode}. */ get spreadMode() { return this._spreadMode; diff --git a/web/interfaces.js b/web/interfaces.js index a8780f9ba..4a027faea 100644 --- a/web/interfaces.js +++ b/web/interfaces.js @@ -18,12 +18,12 @@ */ class IPDFLinkService { /** - * @returns {number} + * @type {number} */ get pagesCount() {} /** - * @returns {number} + * @type {number} */ get page() {} @@ -33,7 +33,7 @@ class IPDFLinkService { set page(value) {} /** - * @returns {number} + * @type {number} */ get rotation() {} @@ -43,7 +43,7 @@ class IPDFLinkService { set rotation(value) {} /** - * @returns {boolean} + * @type {boolean} */ get externalLinkEnabled() {} @@ -117,12 +117,12 @@ class IPDFHistory { */ class IRenderableView { /** - * @returns {string} - Unique ID for rendering queue. + * @type {string} - Unique ID for rendering queue. */ get renderingId() {} /** - * @returns {RenderingStates} + * @type {RenderingStates} */ get renderingState() {} diff --git a/web/pdf_cursor_tools.js b/web/pdf_cursor_tools.js index d7965aca0..537144123 100644 --- a/web/pdf_cursor_tools.js +++ b/web/pdf_cursor_tools.js @@ -55,7 +55,7 @@ class PDFCursorTools { } /** - * @returns {number} One of the values in {CursorTool}. + * @type {number} One of the values in {CursorTool}. */ get activeTool() { return this.active; diff --git a/web/pdf_find_controller.js b/web/pdf_find_controller.js index 95cac21a4..63ba44dc4 100644 --- a/web/pdf_find_controller.js +++ b/web/pdf_find_controller.js @@ -223,7 +223,7 @@ class PDFFindController { } /** - * @return {string} The (current) normalized search query. + * @type {string} The (current) normalized search query. */ get _query() { if (this._state.query !== this._rawQuery) { diff --git a/web/pdf_history.js b/web/pdf_history.js index 74042ba39..e8f29a83d 100644 --- a/web/pdf_history.js +++ b/web/pdf_history.js @@ -272,7 +272,7 @@ class PDFHistory { } /** - * @returns {boolean} Indicating if the user is currently moving through the + * @type {boolean} Indicating if the user is currently moving through the * browser history, useful e.g. for skipping the next 'hashchange' event. */ get popStateInProgress() { diff --git a/web/pdf_link_service.js b/web/pdf_link_service.js index a34c4fe71..a663e5da8 100644 --- a/web/pdf_link_service.js +++ b/web/pdf_link_service.js @@ -64,14 +64,14 @@ class PDFLinkService { } /** - * @returns {number} + * @type {number} */ get pagesCount() { return this.pdfDocument ? this.pdfDocument.numPages : 0; } /** - * @returns {number} + * @type {number} */ get page() { return this.pdfViewer.currentPageNumber; @@ -85,7 +85,7 @@ class PDFLinkService { } /** - * @returns {number} + * @type {number} */ get rotation() { return this.pdfViewer.pagesRotation; @@ -428,14 +428,14 @@ class SimpleLinkService { } /** - * @returns {number} + * @type {number} */ get pagesCount() { return 0; } /** - * @returns {number} + * @type {number} */ get page() { return 0; @@ -447,7 +447,7 @@ class SimpleLinkService { set page(value) {} /** - * @returns {number} + * @type {number} */ get rotation() { return 0; diff --git a/web/pdf_sidebar.js b/web/pdf_sidebar.js index 3cb72907d..bb77ab19d 100644 --- a/web/pdf_sidebar.js +++ b/web/pdf_sidebar.js @@ -109,7 +109,7 @@ class PDFSidebar { } /** - * @returns {number} One of the values in {SidebarView}. + * @type {number} One of the values in {SidebarView}. */ get visibleView() { return (this.isOpen ? this.active : SidebarView.NONE); diff --git a/web/pdf_sidebar_resizer.js b/web/pdf_sidebar_resizer.js index 71d557ffe..d4fd11bee 100644 --- a/web/pdf_sidebar_resizer.js +++ b/web/pdf_sidebar_resizer.js @@ -65,7 +65,7 @@ class PDFSidebarResizer { } /** - * returns {number} + * @type {number} */ get outerContainerWidth() { if (!this._outerContainerWidth) { diff --git a/web/secondary_toolbar.js b/web/secondary_toolbar.js index 853227dd8..11b9fb948 100644 --- a/web/secondary_toolbar.js +++ b/web/secondary_toolbar.js @@ -132,7 +132,7 @@ class SecondaryToolbar { } /** - * @return {boolean} + * @type {boolean} */ get isOpen() { return this.opened; 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 5/9] 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, }) { From 36c01c2c2a7b20b651a15549f4205cc4c476689f Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sun, 13 Oct 2019 14:21:39 +0200 Subject: [PATCH 6/9] Deduplicate the documentation for `PDFDocumentLoadingTask` and `PDFWorker` Both classes live inside a closure with the same name, which confuses JSDoc. Move the documentation to the inner class to deduplicate them. --- src/display/api.js | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/src/display/api.js b/src/display/api.js index d6d41102f..0e585a24f 100644 --- a/src/display/api.js +++ b/src/display/api.js @@ -416,15 +416,14 @@ function _fetchDocument(worker, source, pdfDataRangeTransport, docId) { }); } -/** - * PDF document loading operation. - * @class - * @alias PDFDocumentLoadingTask - */ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() { let nextDocumentId = 0; - /** @constructs PDFDocumentLoadingTask */ + /** + * The loading task controls the operations required to load a PDF document + * (such as network requests) and provides a way to listen for completion, + * after which individual pages can be rendered. + */ class PDFDocumentLoadingTask { constructor() { this._capability = createPromiseCapability(); @@ -1507,12 +1506,6 @@ class LoopbackPort { * constants from {VerbosityLevel} should be used. */ -/** - * PDF.js web worker abstraction, it controls instantiation of PDF documents and - * WorkerTransport for them. If creation of a web worker is not possible, - * a "fake" worker will be used instead. - * @class - */ const PDFWorker = (function PDFWorkerClosure() { const pdfWorkerPorts = new WeakMap(); let nextFakeWorkerId = 0; @@ -1590,9 +1583,15 @@ const PDFWorker = (function PDFWorkerClosure() { } /** - * @param {PDFWorkerParameters} params - The worker initialization parameters. + * PDF.js web worker abstraction, which controls the instantiation of PDF + * documents. Message handlers are used to pass information from the main + * thread to the worker thread and vice versa. If the creation of a web + * worker is not possible, a "fake" worker will be used instead. */ class PDFWorker { + /** + * @param {PDFWorkerParameters} params - Worker initialization parameters. + */ constructor({ name = null, port = null, verbosity = getVerbosityLevel(), } = {}) { if (port && pdfWorkerPorts.has(port)) { From 9f4d45ddf440090ab9c248ec46a1c2c75a822c6c Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sun, 13 Oct 2019 14:28:15 +0200 Subject: [PATCH 7/9] Don't include private methods in the the `PDFPageProxy` API documentation --- src/display/api.js | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/src/display/api.js b/src/display/api.js index 0e585a24f..4ff888fcd 100644 --- a/src/display/api.js +++ b/src/display/api.js @@ -1193,7 +1193,8 @@ class PDFPageProxy { } /** - * Destroys page object. + * Destroys the page object. + * @private */ _destroy() { this.destroyed = true; @@ -1236,9 +1237,8 @@ class PDFPageProxy { } /** - * For internal use only. Attempts to clean up if rendering is in a state - * where that's possible. - * @ignore + * Attempts to clean up if rendering is in a state where that's possible. + * @private */ _tryCleanup(resetStats = false) { if (!this.pendingCleanup || @@ -1262,8 +1262,7 @@ class PDFPageProxy { } /** - * For internal use only. - * @ignore + * @private */ _startRenderPage(transparency, intent) { const intentState = this.intentStates[intent]; @@ -1279,8 +1278,7 @@ class PDFPageProxy { } /** - * For internal use only. - * @ignore + * @private */ _renderPageChunk(operatorListChunk, intentState) { // Add the new chunk to the current operator list. @@ -1302,8 +1300,7 @@ class PDFPageProxy { } /** - * For internal use only. - * @ignore + * @private */ _pumpOperatorList(args) { assert(args.intent, @@ -1356,8 +1353,7 @@ class PDFPageProxy { } /** - * For internal use only. - * @ignore + * @private */ _abortOperatorList({ intentState, reason, force = false, }) { assert(reason instanceof Error, From 92155f6a5f5f31642fe5ba56963d78a4df955120 Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 18:37:55 +0200 Subject: [PATCH 8/9] Don't include `src/shared/util.js` for the API documentation This file only contains helper functions and should not be listed in the documentation since they are not part of the public API. --- gulpfile.js | 1 - 1 file changed, 1 deletion(-) diff --git a/gulpfile.js b/gulpfile.js index 143640f9e..df71613f5 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -959,7 +959,6 @@ gulp.task('jsdoc', function (done) { var JSDOC_FILES = [ 'src/doc_helper.js', 'src/display/api.js', - 'src/shared/util.js', ]; rimraf(JSDOC_BUILD_DIR, function () { From ec6a99d7815a53b3f664d543c204fa5232995d0f Mon Sep 17 00:00:00 2001 From: Tim van der Meij Date: Sat, 12 Oct 2019 18:33:49 +0200 Subject: [PATCH 9/9] Bundle all API documentation in a module This commit allows JSDoc to generate all API documentation in the `pdfjsLib` module (namespace) so the documentation becomes easier to navigate. --- src/display/api.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/display/api.js b/src/display/api.js index 4ff888fcd..5114caf69 100644 --- a/src/display/api.js +++ b/src/display/api.js @@ -15,6 +15,10 @@ /* globals requirejs, __non_webpack_require__ */ /* eslint no-var: error */ +/** + * @module pdfjsLib + */ + import { AbortException, assert, createPromiseCapability, getVerbosityLevel, info, InvalidPDFException, isArrayBuffer, isSameOrigin, MissingPDFException,