Improve the JSDoc comments

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

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

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;

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

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',
@@ -253,7 +254,7 @@ class Annotation {
   }
 
   /**
-   * @return {boolean}
+   * @type {boolean}
    */
   get viewable() {
     if (this.flags === 0) {
@@ -263,7 +264,7 @@ class Annotation {
   }
 
   /**
-   * @return {boolean}
+   * @type {boolean}
    */
   get printable() {
     if (this.flags === 0) {
@@ -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) {
@@ -530,7 +531,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 +643,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 +656,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)) {
@@ -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) {

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

src/core/core_utils.js

@@ -95,10 +95,10 @@ 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.
+ * @returns {string} The resulting Roman number.
  */
 function toRomanNumerals(number, lowerCase = false) {
   assert(Number.isInteger(number) && number > 0,

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

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

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

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

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