Skip to content

Commit

Permalink
Chore: Fix ESLint warnings (JSDoc cleanup) (#199)
Browse files Browse the repository at this point in the history
  • Loading branch information
tonyjin authored Jul 6, 2017
1 parent edd11e4 commit d4303aa
Show file tree
Hide file tree
Showing 35 changed files with 252 additions and 125 deletions.
1 change: 1 addition & 0 deletions .eslintignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
src/third-party/*
dist/*
**/__tests__/*
7 changes: 4 additions & 3 deletions .eslintrc
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
]
Expand Down
5 changes: 2 additions & 3 deletions src/lib/Popup.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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) => {
Expand Down
2 changes: 1 addition & 1 deletion src/lib/annotations/AnnotationDialog.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
10 changes: 6 additions & 4 deletions src/lib/annotations/AnnotationService.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
4 changes: 2 additions & 2 deletions src/lib/annotations/BoxAnnotations.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down
31 changes: 14 additions & 17 deletions src/lib/annotations/CommentBox.js
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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();
Expand All @@ -94,8 +95,7 @@ class CommentBox extends EventEmitter {

/**
* Focus on the text box.
*
* @public
*
* @return {void}
*/
focus() {
Expand All @@ -108,8 +108,7 @@ class CommentBox extends EventEmitter {

/**
* Clear out the text box.
*
* @public
*
* @return {void}
*/
clear() {
Expand All @@ -123,7 +122,6 @@ class CommentBox extends EventEmitter {
/**
* Hide the element.
*
* @public
* @return {void}
*/
hide() {
Expand All @@ -137,7 +135,6 @@ class CommentBox extends EventEmitter {
/**
* Show the element.
*
* @public
* @return {void}
*/
show() {
Expand All @@ -150,9 +147,9 @@ class CommentBox extends EventEmitter {
}

/**
* Destructor
* [destructor]
*
* @public
* @return {void}
*/
destroy() {
if (!this.containerEl) {
Expand Down Expand Up @@ -196,7 +193,7 @@ class CommentBox extends EventEmitter {

/**
* Clear the current text in the textarea element and notify listeners.
*
*
* @private
* @return {void}
*/
Expand All @@ -207,7 +204,7 @@ class CommentBox extends EventEmitter {

/**
* Notify listeners of submit event and then clear textarea element.
*
*
* @private
* @return {void}
*/
Expand All @@ -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
*/
Expand Down
25 changes: 22 additions & 3 deletions src/lib/annotations/annotatorUtil.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
*/
Expand All @@ -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
Expand All @@ -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}
*/
Expand All @@ -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}
*/
Expand All @@ -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}
*/
Expand All @@ -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}
*/
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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 === '';
Expand All @@ -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) {
Expand Down Expand Up @@ -263,6 +278,7 @@ export function getDimensionScale(dimensions, fileDimensions, zoomScale, heightP

/**
* Escapes HTML.
*
* @param {string} str - Input string
* @return {string} HTML escaped string
*/
Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand Down
16 changes: 10 additions & 6 deletions src/lib/annotations/doc/CreateHighlightDialog.js
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -171,9 +174,9 @@ class CreateHighlightDialog extends EventEmitter {
}

/**
* Destructor
* [destructor]
*
* @public
* @return {void}
*/
destroy() {
if (!this.containerEl) {
Expand Down Expand Up @@ -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() {
Expand All @@ -221,7 +224,7 @@ class CreateHighlightDialog extends EventEmitter {

/**
* Fire an event notifying that the plain highlight button has been clicked.
*
*
* @return {void}
*/
onHighlightClick() {
Expand Down Expand Up @@ -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) {
Expand All @@ -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.
Expand Down
Loading

0 comments on commit d4303aa

Please sign in to comment.