Chore: Fix ESLint warnings (JSDoc cleanup) (#199)

.eslintignore

@@ -1,2 +1,3 @@
 src/third-party/*
 dist/*
+**/__tests__/*

.eslintrc

@@ -109,11 +109,12 @@
                     "class": "constructor"
                 },
                 "preferType": {
-                    "object": "Object",
                     "array": "Array",
-                    "String": "string",
+                    "function": "Function",
+                    "object": "Object",
                     "Boolean": "boolean",
-                    "Number": "number"
+                    "Number": "number",
+                    "String": "string"
                 }
             }
         ]

src/lib/Popup.js

@@ -75,9 +75,8 @@ class Popup {
      * Shows a popup with a message.
      *
      * @param {string} message - Popup message
-     * @param {string} buttonText - Button text
-     * @param {function} [buttonHandler] - Optional onclick function for the button
      * @param {string} [buttonText] - Optional text to show in button
+     * @param {Function} [buttonHandler] - Optional onclick function for the button
      * @return {void}
      */
     show(message, buttonText, buttonHandler) {
@@ -185,7 +184,7 @@ class Popup {
     /**
      * Keydown handler for popup
      *
-     * @param {string} key - Keydown key
+     * @param {Event} event - Keydown event
      * @return {boolean} Consumed or not
      */
     keydownHandler = (event) => {

src/lib/annotations/AnnotationDialog.js

@@ -209,7 +209,7 @@ const CLASS_ANIMATE_DIALOG = 'bp-animate-show-dialog';
     /**
      * Posts an annotation in the dialog.
      *
-     * @public
+     * @param {string} [textInput] - Annotation text to post
      * @return {void}
      */
     postAnnotation(textInput) {

src/lib/annotations/AnnotationService.js

@@ -244,8 +244,8 @@ const ANONYMOUS_USER = {
      *
      * @private
      * @param {string} fileVersionId - File version ID to fetch annotations for
-     * @param {string} marker - marker to use if there are more than limit annotations
-     *  * @param {int} limit - the amout of annotations the API will return per call
+     * @param {string} marker - Marker to use if there are more than limit annotations
+     * @param {int} limit - The amout of annotations the API will return per call
      * @return {Promise} Promise that resolves with fetched annotations
      */
     getReadUrl(fileVersionId, marker = null, limit = null) {
@@ -266,9 +266,11 @@ const ANONYMOUS_USER = {
      * limit is 100 annotations per API call.
      *
      * @private
+     * @param {Function} resolve - Promise resolution handler
+     * @param {Function} reject - Promise rejection handler
      * @param {string} fileVersionId - File version ID to fetch annotations for
-     * @param {string} marker - marker to use if there are more than limit annotations
-     * @param {int} limit - the amout of annotations the API will return per call
+     * @param {string} marker - Marker to use if there are more than limit annotations
+     * @param {int} limit - The amout of annotations the API will return per call
      * @return {void}
      */
     readFromMarker(resolve, reject, fileVersionId, marker = null, limit = null) {

src/lib/annotations/BoxAnnotations.js

@@ -36,9 +36,9 @@ class BoxAnnotations {
     }
 
     /**
-     * Chooses a annotator based on file extension.
+     * Chooses a annotator based on viewer.
      *
-     * @param {Object} file - Box file
+     * @param {Object} viewer - Current preview viewer
      * @param {Array} [disabledAnnotators] - List of disabled annotators
      * @return {Object} The annotator to use
      */

src/lib/annotations/CommentBox.js

@@ -10,21 +10,21 @@ const TEXT_ADD_COMMENT_PLACEHOLDER = __('annotation_add_comment_placeholder');
 class CommentBox extends EventEmitter {
     /**
      * Text displayed in the Cancel button element.
-     * 
+     *
      * @property {string}
      */
     cancelText = TEXT_ANNOTATION_CANCEL;
 
     /**
      * Text displayed in the Post button element.
-     * 
+     *
      * @property {string}
      */
     postText = TEXT_ANNOTATION_POST;
 
     /**
      * Placeholder text displayed in the text area element.
-     * 
+     *
      * @property {string}
      */
     placeholderText = TEXT_ADD_COMMENT_PLACEHOLDER;
@@ -73,10 +73,11 @@ class CommentBox extends EventEmitter {
     /**
      * Creates an element for text entry, submission and cancellation.
      *
+     * @param {HTMLElement} parentEl - Parent element
      * @param {Object} [config] - Object containing text values to be displayed to the user.
-     * config.cancel - Text displayed in the "Cancel" button
-     * config.post - Text displayed in the "Post" button
-     * config.placeholder - Placeholder text displayed in the text area
+     * @param {string} config.cancel - Text displayed in the "Cancel" button
+     * @param {string} config.post - Text displayed in the "Post" button
+     * @param {string} config.placeholder - Placeholder text displayed in the text area
      */
     constructor(parentEl, config = {}) {
         super();
@@ -94,8 +95,7 @@ class CommentBox extends EventEmitter {
 
     /**
      * Focus on the text box.
-     * 
-     * @public
+     *
      * @return {void}
      */
     focus() {
@@ -108,8 +108,7 @@ class CommentBox extends EventEmitter {
 
     /**
      * Clear out the text box.
-     * 
-     * @public
+     *
      * @return {void}
      */
     clear() {
@@ -123,7 +122,6 @@ class CommentBox extends EventEmitter {
     /**
      * Hide the element.
      *
-     * @public
      * @return {void}
      */
     hide() {
@@ -137,7 +135,6 @@ class CommentBox extends EventEmitter {
     /**
      * Show the element.
      *
-     * @public
      * @return {void}
      */
     show() {
@@ -150,9 +147,9 @@ class CommentBox extends EventEmitter {
     }
 
     /**
-     * Destructor
+     * [destructor]
      *
-     * @public
+     * @return {void}
      */
     destroy() {
         if (!this.containerEl) {
@@ -196,7 +193,7 @@ class CommentBox extends EventEmitter {
 
     /**
      * Clear the current text in the textarea element and notify listeners.
-     * 
+     *
      * @private
      * @return {void}
      */
@@ -207,7 +204,7 @@ class CommentBox extends EventEmitter {
 
     /**
      * Notify listeners of submit event and then clear textarea element.
-     * 
+     *
      * @private
      * @return {void}
      */
@@ -219,7 +216,7 @@ class CommentBox extends EventEmitter {
     /**
      * Create HTML for the comment box. Assigns references to elements, attach event listeners.
      * ie) Post button, cancel button
-     * 
+     *
      * @private
      * @return {HTMLElement} The HTML to append to this.parentElement
      */

src/lib/annotations/annotatorUtil.js

@@ -18,6 +18,7 @@ const THREAD_PARAMS = [
 
 /**
  * Finds the closest ancestor DOM element with the specified class.
+ *
  * @param {HTMLElement} element - Element to search ancestors of
  * @param {string} className - Class name to query
  * @return {HTMLElement|null} Closest ancestor with given class or null
@@ -34,6 +35,7 @@ export function findClosestElWithClass(element, className) {
 
 /**
 * Returns the page element and page number that the element is on.
+*
 * @param {HTMLElement} element - Element to find page and page number for
 * @return {Object} Page element/page number if found or null/-1 if not
 */
@@ -52,6 +54,7 @@ export function getPageInfo(element) {
  * Finds the closest element with a data type and returns that data type. If
  * an attributeName is provided, search for that data atttribute instead of
  * data type.
+ *
  * @param {HTMLElement} element - Element to find closest data type for
  * @param {string} [attributeName] - Optional different data attribute to search
  * for
@@ -71,6 +74,7 @@ export function findClosestDataType(element, attributeName) {
 
 /**
  * Shows the specified element or element with specified selector.
+ *
  * @param {HTMLElement|string} elementOrSelector - Element or CSS selector
  * @return {void}
  */
@@ -87,6 +91,7 @@ export function showElement(elementOrSelector) {
 
 /**
  * Hides the specified element or element with specified selector.
+ *
  * @param {HTMLElement|string} elementOrSelector - Element or CSS selector
  * @return {void}
  */
@@ -103,6 +108,7 @@ export function hideElement(elementOrSelector) {
 
 /**
  * Shows the specified element or element with specified selector.
+ *
  * @param {HTMLElement|string} elementOrSelector - Element or CSS selector
  * @return {void}
  */
@@ -120,6 +126,7 @@ export function showInvisibleElement(elementOrSelector) {
 /**
  * Hides the specified element or element with specified selector. The element
  * will still take up DOM space but not be visible in the UI
+ *
  * @param {HTMLElement|string} elementOrSelector - Element or CSS selector
  * @return {void}
  */
@@ -137,8 +144,9 @@ export function hideElementVisibility(elementOrSelector) {
 /**
  * Reset textarea element - clears value, resets styles, and remove active
  * state.
+ *
  * @param {HTMLElement} element - Textarea to reset
- * @param {Boolean} clearText - Whether or not text in text area should be cleared
+ * @param {boolean} clearText - Whether or not text in text area should be cleared
  * @return {void}
  */
 export function resetTextarea(element, clearText) {
@@ -158,6 +166,8 @@ export function resetTextarea(element, clearText) {
 
 /**
  * Checks whether element is fully in viewport.
+ *
+ * @param {HTMLElement} element - Element to check
  * @return {boolean} Whether element is fully in viewport
  */
 export function isElementInViewport(element) {
@@ -175,6 +185,7 @@ export function isElementInViewport(element) {
  * Returns avatar image HTML for annotation dialog. This will be either an
  * image with the supplied avatar URL as a source if there is a URL passed in
  * or one generated using the initials of the annotator.
+ *
  * @param {string} avatarUrl - URL of avatar photo
  * @param {string} userId - User ID of annotator
  * @param {string} userName - Username of annotator
@@ -197,6 +208,7 @@ export function getAvatarHtml(avatarUrl, userId, userName) {
 
 /**
  * Returns zoom scale of annotated element.
+ *
  * @param {HTMLElement} annotatedElement - HTML element being annotated on
  * @return {number} Zoom scale
  */
@@ -210,8 +222,9 @@ export function getScale(annotatedElement) {
 
 /**
  * Whether or not a highlight annotation has comments or is a plain highlight
- * @param {Annotation[]} Annotations - in highlight thread
- * @return {Boolean} Whether annotation is a plain highlight annotation
+ *
+ * @param {Annotation[]} annotations - Annotations in highlight thread
+ * @return {boolean} Whether annotation is a plain highlight annotation
  */
 export function isPlainHighlight(annotations) {
     return annotations.length === 1 && annotations[0].text === '';
@@ -220,6 +233,8 @@ export function isPlainHighlight(annotations) {
 /**
  * Returns whether or not the annotation type is 'highlight' or
  * 'highlight-comment'
+ *
+ * @param {string} type - Annotatation type
  * @return {boolean} Whether or not annotation is a highlight
  */
 export function isHighlightAnnotation(type) {
@@ -263,6 +278,7 @@ export function getDimensionScale(dimensions, fileDimensions, zoomScale, heightP
 
 /**
  * Escapes HTML.
+ *
  * @param {string} str - Input string
  * @return {string} HTML escaped string
  */
@@ -280,6 +296,7 @@ export function htmlEscape(str) {
  * Repositions caret if annotations dialog will run off the right or left
  * side of the page. Otherwise positions caret at the center of the
  * annotations dialog and the updated left corner x coordinate.
+ *
  * @param  {HTMLElement} dialogEl Annotations dialog element
  * @param  {number} dialogX Left corner x coordinate of the annotations dialog
  * @param  {number} highlightDialogWidth Width of the annotations dialog
@@ -318,6 +335,8 @@ export function repositionCaret(dialogEl, dialogX, highlightDialogWidth, browser
 
 /**
  * Checks thread is in a pending or pending-active state
+ *
+ * @param {string} threadState - State of thread
  * @return {boolean} Whether annotation thread is in a pending state
  */
 export function isPending(threadState) {

src/lib/annotations/doc/CreateHighlightDialog.js

@@ -89,8 +89,11 @@ class CreateHighlightDialog extends EventEmitter {
 
     /**
      * A dialog used to create plain and comment highlights.
-     * 
+     *
      * [constructor]
+     *
+     * @param {HTMLElement} parentEl - Parent element
+     * @return {CreateHighlightDialog} CreateHighlightDialog instance
      */
     constructor(parentEl) {
         super();
@@ -171,9 +174,9 @@ class CreateHighlightDialog extends EventEmitter {
     }
 
     /**
-     * Destructor
+     * [destructor]
      *
-     * @public
+     * @return {void}
      */
     destroy() {
         if (!this.containerEl) {
@@ -209,7 +212,7 @@ class CreateHighlightDialog extends EventEmitter {
     /**
      * Update the position styling for the dialog so that the chevron points to
      * the desired location.
-     * 
+     *
      * @return {void}
      */
     updatePosition() {
@@ -221,7 +224,7 @@ class CreateHighlightDialog extends EventEmitter {
 
     /**
      * Fire an event notifying that the plain highlight button has been clicked.
-     * 
+     *
      * @return {void}
      */
     onHighlightClick() {
@@ -271,6 +274,7 @@ class CreateHighlightDialog extends EventEmitter {
      * Hide or show the plain and comment buttons, in the dialog.
      *
      * @param {boolean} visible - If true, shows the plain and comment buttons
+     * @return {void}
      */
     setButtonVisibility(visible) {
         if (visible) {
@@ -281,7 +285,7 @@ class CreateHighlightDialog extends EventEmitter {
     }
 
     /**
-     * Stop the dialog from propagating events to parent container. Pairs with 
+     * Stop the dialog from propagating events to parent container. Pairs with
      * giving focus to the text area in the comment box and clicking "Post".
      *
      * @param {Event} event - The DOM event coming from interacting with the element.