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

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

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

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

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

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;

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