mirrors/pdf.js
1
0
Fork 0
mirror of https://github.com/mozilla/pdf.js.git synced 2025-04-22 16:18:08 +02:00
Code Activity

Consistently use square brackets for optional parameters in JSDoc comments

Browse source 
Square brackets are recommended to indicate optional parameters. Using
them helps for automatically generating correct documentation.
This commit is contained in:
Tim van der Meij 2019-10-12 16:30:32 +02:00
parent efd331daa1
commit f4daafc077
No known key found for this signature in database
GPG key ID: 8C3FD2925A5F2762
21 changed files with 136 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

8
web/annotation_layer_builder.js
View file

@ -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}

14
web/app.js
View file

@ -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',

57
web/base_viewer.js
View file

@ -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: <page-ref> </XYZ|/FitXXX> <args..>
* @property {boolean} allowNegativeOffset - (optional) Allow negative page
* offsets. The default value is `false`.
* @property {Array} [destArray] - The original PDF destination array, in the
* format: <page-ref> </XYZ|/FitXXX> <args..>
* @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}

10
web/chromecom.js
View file

@ -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 = {

12
web/firefoxcom.js
View file

@ -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('');

4
web/interfaces.js
View file

@ -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}

14
web/overlay_manager.js
View file

@ -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.
*/

6
web/pdf_cursor_tools.js
View file

@ -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 {

10
web/pdf_history.js
View file

@ -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.
*/

8
web/pdf_link_service.js
View file

@ -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.
*/
/**

22
web/pdf_page_view.js
View file

@ -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.
*/

6
web/pdf_presentation_mode.js
View file

@ -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 {

8
web/pdf_sidebar.js
View file

@ -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);

6
web/pdf_thumbnail_view.js
View file

@ -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.
*/

4
web/text_layer_builder.js
View file

@ -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) {