From 9ae38534a96fb7818686eeba8c732f9a1cc6f055 Mon Sep 17 00:00:00 2001 From: Jeremy Press Date: Wed, 23 Aug 2017 17:44:30 -0700 Subject: [PATCH] Chore: Updating method decorators (#311) --- src/lib/Browser.js | 6 ++++++ src/lib/Cache.js | 12 +++++++++--- src/lib/Controls.js | 8 +++++++- src/lib/Fullscreen.js | 2 +- src/lib/Logger.js | 8 ++++++++ src/lib/Notification.js | 3 +++ src/lib/Popup.js | 9 +++++++++ src/lib/Preview.js | 22 ++++++++++++++++++++-- src/lib/PreviewUI.js | 10 ++++++++++ src/lib/ProgressBar.js | 2 ++ src/lib/RepStatus.js | 1 + src/lib/file.js | 11 ++++++++++- src/lib/tokens.js | 2 ++ src/lib/util.js | 31 +++++++++++++++++++++++++++++++ 14 files changed, 119 insertions(+), 8 deletions(-) diff --git a/src/lib/Browser.js b/src/lib/Browser.js index 5e37947ff..6fb914dad 100644 --- a/src/lib/Browser.js +++ b/src/lib/Browser.js @@ -278,6 +278,7 @@ class Browser { /** * Returns whether the browser is a mobile browser. * + * @public * @return {boolean} true if browser supports download */ static isMobile() { @@ -289,6 +290,8 @@ class Browser { * Returns whether the browser can download via HTML5. taken from Modernizr: * https://github.com/Modernizr/Modernizr/blob/master/feature-detects/a/download.js * Currently not supported by IE11 or Safari 10.0 http://caniuse.com/#feat=download + * + * @public * @return {boolean} true if browser supports download */ static canDownload() { @@ -298,6 +301,7 @@ class Browser { /** * Returns whether or not the device is running IOS * + * @public * @return {boolean} true if the device is running IOS */ static isIOS() { @@ -307,6 +311,7 @@ class Browser { /** * Returns whether or not the device is running Android * + * @public * @return {boolean} true if the device is running Android */ static isAndroid() { @@ -316,6 +321,7 @@ class Browser { /** * Returns whether or not the device is running IOS 10.3.x that has Font Ligature rendering issue. * + * @public * @return {boolean} Whether device is running 10.3.x */ static isIOSWithFontIssue() { diff --git a/src/lib/Cache.js b/src/lib/Cache.js index e0f91240c..8beb42d07 100644 --- a/src/lib/Cache.js +++ b/src/lib/Cache.js @@ -16,6 +16,7 @@ class Cache { * Caches a simple object in memory and in localStorage if specified. * Note that objects cached in localStorage will be stringified. * + * @public * @param {string} key - The cache key * @param {*} value - The cache value * @param {boolean} useLocalStorage - Whether or not to use localStorage @@ -32,6 +33,7 @@ class Cache { /** * Deletes object from in-memory cache and localStorage. * + * @public * @param {string} key - The cache key * @return {void} */ @@ -46,6 +48,7 @@ class Cache { /** * Checks if cache has provided key. * + * @public * @param {string} key - The cache key * @return {boolean} Whether the cache has key */ @@ -58,8 +61,9 @@ class Cache { * tries to fetch from localStorage. If fetched from localStorage, object * will be a JSON parsed object. * + * @public * @param {string} key - Key of cached object - * @return {*} Cached object + * @return {Object} Cached object */ get(key) { if (this.inCache(key)) { @@ -87,6 +91,7 @@ class Cache { /** * Checks if memory cache has provided key. * + * @private * @param {string} key - The cache key * @return {boolean} Whether the cache has key */ @@ -97,6 +102,7 @@ class Cache { /** * Checks if memory cache has provided key. * + * @private * @param {string} key - The cache key * @return {boolean} Whether the cache has key */ @@ -117,8 +123,8 @@ class Cache { * localStorage was available the first time this is called, but becomes * unavailable at a later time. * - * @return {boolean} Whether or not localStorage is available or not. * @private + * @return {boolean} Whether or not localStorage is available or not. */ localStorageAvailable() { if (this.available === undefined) { @@ -139,9 +145,9 @@ class Cache { * Generates a key to use for localStorage from the provided key. This * should prevent name collisions. * + * @private * @param {string} key - Generate key from this key * @return {string} Generated key for localStorage - * @private */ generateKey(key) { return `bp-${key}`; diff --git a/src/lib/Controls.js b/src/lib/Controls.js index e4aa84f45..3caa8ab84 100644 --- a/src/lib/Controls.js +++ b/src/lib/Controls.js @@ -142,6 +142,7 @@ class Controls { /** * Handles all focusin events for the module. * + * @private * @param {Event} event - A DOM-normalized event object. * @return {void} */ @@ -156,6 +157,7 @@ class Controls { /** * Handles all focusout events for the module. * + * @private * @param {Event} event - A DOM-normalized event object. * @return {void} */ @@ -169,6 +171,7 @@ class Controls { /** * Handles click events for the control bar. * + * @private * @param {Event} event - A DOM-normalized event object. * @return {void} */ @@ -180,7 +183,7 @@ class Controls { /** * Adds buttons to controls * - * @private + * @public * @param {string} text - button text * @param {Function} handler - button handler * @param {string} [classList] - optional class list @@ -216,6 +219,7 @@ class Controls { /** * Enables the controls. * + * @public * @return {void} */ enable() { @@ -225,6 +229,7 @@ class Controls { /** * Disables the controls. * + * @public * @return {void} */ disable() { @@ -234,6 +239,7 @@ class Controls { /** * Determines if the page number input is focused. * + * @public * @return {boolean} Is the input focused */ isPageNumFocused() { diff --git a/src/lib/Fullscreen.js b/src/lib/Fullscreen.js index b98b89ff6..e44739709 100644 --- a/src/lib/Fullscreen.js +++ b/src/lib/Fullscreen.js @@ -81,7 +81,7 @@ class Fullscreen extends EventEmitter { /** * Toggles fullscreen mode * - * @private + * @public * @param {HTMLElement} el - fullscreen element * @return {void} */ diff --git a/src/lib/Logger.js b/src/lib/Logger.js index e05b80cb3..50c848760 100644 --- a/src/lib/Logger.js +++ b/src/lib/Logger.js @@ -38,6 +38,7 @@ class Logger { /** * Gets browser capability information. * + * @private * @return {Object} Browser capability information */ getBrowserInfo() { @@ -61,6 +62,7 @@ class Logger { /** * Marks file as cached. * + * @public * @return {void} */ setCached() { @@ -70,6 +72,7 @@ class Logger { /** * Marks file as stale cache. * + * @public * @return {void} */ setCacheStale() { @@ -79,6 +82,7 @@ class Logger { /** * Marks file as converted. * + * @public * @return {void} */ setUnConverted() { @@ -89,6 +93,7 @@ class Logger { /** * Marks file as preloaded. * + * @public * @return {void} */ setPreloaded() { @@ -98,6 +103,7 @@ class Logger { /** * Sets the file object. * + * @public * @param {Object} file - file object * @return {void} */ @@ -108,6 +114,7 @@ class Logger { /** * Sets the file type. * + * @public * @param {string} type - content type * @return {void} */ @@ -118,6 +125,7 @@ class Logger { /** * Finishes logging. * + * @public * @param {Object} count - Preview count * @return {Object} Metrics object */ diff --git a/src/lib/Notification.js b/src/lib/Notification.js index 2d10fd395..5fdb705b5 100644 --- a/src/lib/Notification.js +++ b/src/lib/Notification.js @@ -39,6 +39,7 @@ class Notification { /** * Shows a notification message. * + * @public * @param {string} message - Notification message * @param {string} [buttonText] - Optional text to show in button * @return {void} @@ -62,6 +63,7 @@ class Notification { /** * Hides the notification message. Does nothing if the notification is already hidden. * + * @public * @return {void} */ hide() { @@ -77,6 +79,7 @@ class Notification { /** * Click handler for notification. * + * @private * @param {Event} event - DOM event * @return {void} */ diff --git a/src/lib/Popup.js b/src/lib/Popup.js index c7a137ffc..c097bc2c8 100644 --- a/src/lib/Popup.js +++ b/src/lib/Popup.js @@ -74,6 +74,7 @@ class Popup { /** * Shows a popup with a message. * + * @public * @param {string} message - Popup message * @param {string} [buttonText] - Optional text to show in button * @param {Function} [buttonHandler] - Optional onclick function for the button @@ -99,6 +100,7 @@ class Popup { /** * Hides the popup message. * + * @public * @return {void} */ hide() { @@ -108,6 +110,7 @@ class Popup { /** * Adds custom content to the modal. * + * @public * @param {string} element - DOM element * @param {boolean} prepend - prepends or appends the content to the content element * @@ -125,6 +128,7 @@ class Popup { /** * Returns whether or not the popup is visible. * + * @public * @return {boolean} Whether or not popup is visible. */ isVisible() { @@ -134,6 +138,7 @@ class Popup { /** * Gets whether or not the button is disabled. * + * @public * @return {boolean} Whether or not button is diabled */ isButtonDisabled() { @@ -143,6 +148,7 @@ class Popup { /** * Disbles the button element. * + * @public * @return {void} */ disableButton() { @@ -153,6 +159,7 @@ class Popup { /** * Enables the button element. * + * @public * @return {void} */ enableButton() { @@ -163,6 +170,7 @@ class Popup { /** * Click handler for popup. * + * @private * @param {Event} event - DOM event * @return {void} */ @@ -184,6 +192,7 @@ class Popup { /** * Keydown handler for popup * + * @private * @param {Event} event - Keydown event * @return {boolean} Consumed or not */ diff --git a/src/lib/Preview.js b/src/lib/Preview.js index 9dc11033b..f27d0142b 100644 --- a/src/lib/Preview.js +++ b/src/lib/Preview.js @@ -148,6 +148,7 @@ class Preview extends EventEmitter { /** * Primary function for showing a preview of a file. * + * @public * @param {string|Object} fileIdOrFile - Box File ID or well-formed Box File object * @param {string|Function} token - Access token string or generator function * @param {Object} [options] - Optional preview options @@ -168,6 +169,7 @@ class Preview extends EventEmitter { /** * Destroys and hides the preview. * + * @public * @return {void} */ hide() { @@ -187,6 +189,7 @@ class Preview extends EventEmitter { /** * Updates files to navigate between. * + * @public * @param {string[]} [collection] - Updated collection of file IDs * @return {void} */ @@ -205,6 +208,7 @@ class Preview extends EventEmitter { * a file is previewed. Note that we only do simple validation that the * expected properties exist before caching. * + * @public * @param {Object[]|Object} [fileMetadata] - Array or single file metadata to cache * @return {void} */ @@ -232,6 +236,7 @@ class Preview extends EventEmitter { /** * Returns the current viewer. * + * @public * @return {Object|undefined} Current viewer */ getCurrentViewer() { @@ -241,6 +246,7 @@ class Preview extends EventEmitter { /** * Returns the current file being previewed. * + * @public * @return {Object|null} Current file */ getCurrentFile() { @@ -250,6 +256,7 @@ class Preview extends EventEmitter { /** * Returns the current file being previewed. * + * @public * @return {Object|null} Current collection */ getCurrentCollection() { @@ -259,6 +266,7 @@ class Preview extends EventEmitter { /** * Returns the list of viewers that Preview supports. * + * @public * @return {string[]} List of supported viewers */ getViewers() { @@ -272,6 +280,7 @@ class Preview extends EventEmitter { /** * Disables one or more viewers. * + * @public * @param {string|string[]} viewers - destroys the container contents * @return {void} */ @@ -288,6 +297,7 @@ class Preview extends EventEmitter { /** * Enables one or more viewers. * + * @public * @param {string|string[]} viewers - destroys the container contents * @return {void} */ @@ -304,6 +314,7 @@ class Preview extends EventEmitter { /** * Disables keyboard shortcuts / hotkeys for Preview. * + * @public * @return {void} */ disableHotkeys() { @@ -313,6 +324,7 @@ class Preview extends EventEmitter { /** * Enables keyboard shortcuts / hotkeys for Preview. * + * @public * @return {void} */ enableHotkeys() { @@ -322,6 +334,7 @@ class Preview extends EventEmitter { /** * Resizes the preview. * + * @public * @return {void} */ resize() { @@ -333,6 +346,7 @@ class Preview extends EventEmitter { /** * Prints the file being previewed if the viewer supports printing. * + * @public * @return {void} */ print() { @@ -344,6 +358,7 @@ class Preview extends EventEmitter { /** * Downloads the file being previewed. * + * @public * @return {void} */ download() { @@ -358,6 +373,7 @@ class Preview extends EventEmitter { * Updates the token Preview uses. Passed in parameter can either be a * string token or token generation function. See tokens.js. * + * @public * @param {string|Function} tokenOrTokenFunc - Either an access token or token * generator function * @param {boolean} [reloadPreview] - Whether or not to reload the current @@ -384,6 +400,7 @@ class Preview extends EventEmitter { * shared link, shared link password) must be used when prefetching and * when the actual view happens. * + * @public * @param {Object} options - Prefetch options * @param {string} options.fileId - Box File ID * @param {string} options.token - Access token @@ -444,6 +461,7 @@ class Preview extends EventEmitter { /** * Prefetches static viewer assets for the specified viewers. * + * @public * @param {string[]} [viewerNames] - Names of viewers to prefetch, defaults to none * @return {void} */ @@ -919,10 +937,10 @@ class Preview extends EventEmitter { * preview happened for access stats, unlike the Logger, which logs preview * errors and performance metrics. * + * @private * @param {string} fileId - File ID to log preview event for * @param {Object} options - File options, e.g. token, shared link * @return {void} - * @private */ logPreviewEvent(fileId, options) { this.logRetryCount = this.logRetryCount || 0; @@ -1127,8 +1145,8 @@ class Preview extends EventEmitter { /** * Mousemove handler for navigation. * - * @return {Function} Throttled mousemove handler * @private + * @return {Function} Throttled mousemove handler */ getGlobalMousemoveHandler() { if (this.throttledMousemoveHandler) { diff --git a/src/lib/PreviewUI.js b/src/lib/PreviewUI.js index fa49fcf30..e36ddb48e 100644 --- a/src/lib/PreviewUI.js +++ b/src/lib/PreviewUI.js @@ -48,6 +48,7 @@ class PreviewUI { /** * Destroy preview container content. * + * @public * @return {void} */ cleanup() { @@ -70,6 +71,7 @@ class PreviewUI { /** * Initializes the container for preview. * + * @public * @param {Object} options - Setup options * @param {Function} keydown - Keydown handler * @param {Function} navigateLeft - Left navigation handler @@ -126,6 +128,7 @@ class PreviewUI { /** * Shows navigation arrows if there is a need * + * @public * @param {number} id - File ID of current preview * @param {number[]} collection - Array of File IDs being previewed * @return {void} @@ -182,6 +185,7 @@ class PreviewUI { /** * Shows the print button if the viewers implement print * + * @public * @param {Function} handler - Print click handler * @return {void} */ @@ -199,6 +203,7 @@ class PreviewUI { /** * Shows the download button if the viewers implement download * + * @public * @param {Function} handler - Download click handler * @return {void} */ @@ -216,6 +221,7 @@ class PreviewUI { /** * Shows the loading download button if the viewers implement download * + * @public * @param {Function} handler - Download click handler * @return {void} */ @@ -233,6 +239,7 @@ class PreviewUI { /** * Shows the loading indicator * + * @public * @return {void} */ showLoadingIndicator() { @@ -244,6 +251,7 @@ class PreviewUI { /** * Hides the loading indicator. * + * @public * @return {void} */ hideLoadingIndicator() { @@ -264,6 +272,7 @@ class PreviewUI { /** * Shows and starts a progress bar at the top of the preview. * + * @public * @return {void} */ startProgressBar() { @@ -273,6 +282,7 @@ class PreviewUI { /** * Finishes and hides the top progress bar if present. * + * @public * @return {void} */ finishProgressBar() { diff --git a/src/lib/ProgressBar.js b/src/lib/ProgressBar.js index 780ac527d..20856d585 100644 --- a/src/lib/ProgressBar.js +++ b/src/lib/ProgressBar.js @@ -48,6 +48,7 @@ class ProgressBar { /** * Start progress bar loading. * + * @public * @return {void} */ start() { @@ -72,6 +73,7 @@ class ProgressBar { /** * Finish progress bar loading and reset. * + * @public * @return {void} */ finish() { diff --git a/src/lib/RepStatus.js b/src/lib/RepStatus.js index 70e5c85c9..15f221677 100644 --- a/src/lib/RepStatus.js +++ b/src/lib/RepStatus.js @@ -8,6 +8,7 @@ class RepStatus extends EventEmitter { /** * Gets the status out of represenation * + * @public * @param {Object} representation - representation object * @return {string} rep status instance */ diff --git a/src/lib/file.js b/src/lib/file.js index 1b3061f88..06a2a80bb 100644 --- a/src/lib/file.js +++ b/src/lib/file.js @@ -20,6 +20,7 @@ const FILE_FIELDS = [ /** * Returns the Box file Content API URL with relevant fields * + * @public * @param {string} id - Box file ID * @param {string} apiHost - Box API base url * @return {string} API url @@ -31,6 +32,7 @@ export function getURL(id, apiHost) { /** * Returns the Box file Content API URL * + * @public * @param {string} id - Box file ID * @param {string} apiHost - Box API base URL * @return {string} API url @@ -42,6 +44,7 @@ export function getDownloadURL(id, apiHost) { /** * Returns the matching representation if file has it. * + * @public * @param {Object} file - Box file * @param {string} repName - Name of representation * @return {Object|null} Maching representation object or null @@ -53,6 +56,7 @@ export function getRepresentation(file, repName) { /** * Is Watermarked * + * @public * @param {Object} file - Box file * @return {boolean} Whether or not file is watermarked */ @@ -63,6 +67,7 @@ export function isWatermarked(file) { /** * Checks permission * + * @public * @param {Object} file - Box file * @param {string} operation - Action to check permission for * @return {boolean} Whether or not action is permitted @@ -74,6 +79,7 @@ export function checkPermission(file, operation) { /** * Checks feature * + * @public * @param {Object} viewer - Viewer instance * @param {string} primary - Primary feature to check * @param {string} [secondary] - Secondary feature to check @@ -88,8 +94,9 @@ export function checkFeature(viewer, primary, secondary) { * Checks whether Box File object is valid by checking whether each property * in FIELDS on the specified file object is defined. * + * @public * @param {Object} file - Box File object to check - * @return {boolean} Whether or not file object structure is valid + * @return {boolean} Whether or not file metadata structure is valid */ export function checkFileValid(file) { if (!file || typeof file !== 'object') { @@ -130,6 +137,7 @@ function addOriginalRepresentation(file) { * Wrapper for caching a file object. Adds the faked 'ORIGINAL' representation * when appropraite before caching. * + * @public * @param {Cache} cache - Cache instance * @param {Object} file - Box file or simple { id: fileId } object * @return {void} @@ -145,6 +153,7 @@ export function cacheFile(cache, file) { /** * Wrapper for uncaching a file object. * + * @public * @param {Cache} cache - Cache instance * @param {Object} file - Box file or simple { id: fileId } object * @return {void} diff --git a/src/lib/tokens.js b/src/lib/tokens.js index 9006fa5ae..99e6acd83 100644 --- a/src/lib/tokens.js +++ b/src/lib/tokens.js @@ -5,6 +5,7 @@ const error = new Error('Missing Auth Token!'); * Helper function to create token map used below. * Maps the same token to multiple files. * + * @private * @param {Array} ids - Box file IDs * @param {string} token - Token to use for map * @return {Object} ID to token map @@ -24,6 +25,7 @@ function createIdTokenMap(ids, token) { * id and value is the token. The function accepts either a simple id * or an array of file ids * + * @public * @param {string|Array} id - box file id(s) * @param {string|Function} token - Token to use or token generation function * @return {Promise} Promise that resolves with ID to token map diff --git a/src/lib/util.js b/src/lib/util.js index 74a37824c..49b97c3ab 100644 --- a/src/lib/util.js +++ b/src/lib/util.js @@ -12,6 +12,7 @@ const CLIENT_VERSION = __VERSION__; /** * Retrieves JSON from response. * + * @private * @param {Response} response - Response to parse * @return {Promise|Response} Response if 204, otherwise promise that resolves with JSON */ @@ -26,6 +27,7 @@ const parseJSON = (response) => { /** * Extract response body as text. * + * @private * @param {Response} response - Response to parse * @return {Promise} Promise that resolves with text */ @@ -34,6 +36,7 @@ const parseText = (response) => response.text(); /** * Extract response body as blob. * + * @private * @param {Response} response - Response to parse * @return {Promise} Promise that resolves with blob */ @@ -42,6 +45,7 @@ const parseBlob = (response) => response.blob(); /** * Pass through response. * + * @private * @param {Response} response - Response to pass through * @return {Response} Unextracted response */ @@ -114,6 +118,7 @@ function createDownloadIframe() { * get(url, type) * get(url) * + * @public * @param {string} url - The URL to fetch * @param {Object} [headers] - Key-value map of headers * @param {string} [type] - response type json (default), text, blob or any @@ -156,6 +161,7 @@ export function get(url, ...rest) { /** * HTTP POSTs a URL with JSON data * + * @public * @param {string} url - The URL to fetch * @param {Object} headers - Key-value map of headers * @param {Object} data - JS Object representation of JSON data to send @@ -168,6 +174,7 @@ export function post(...rest) { /** * HTTP PUTs a URL with JSON data * + * @public * @param {string} url - The URL to fetch * @param {Object} headers - Key-value map of headers * @param {Object} data - JS Object representation of JSON data to send @@ -180,6 +187,7 @@ export function del(...rest) { /** * HTTP PUTs a url with JSON data * + * @public * @param {string} url - The url to fetch * @param {Object} headers - Key-value map of headers * @param {Object} data - JS Object representation of JSON data to send @@ -193,6 +201,7 @@ export function put(...rest) { * Opens url in an iframe * Used for downloads * + * @public * @param {string} url - URL to open * @return {HTMLElement} IFrame element */ @@ -206,6 +215,7 @@ export function openUrlInsideIframe(url) { * Opens content in an iframe * Used for printing * + * @public * @param {string} content - HTML content * @return {HTMLElement} Iframe element */ @@ -219,6 +229,7 @@ export function openContentInsideIframe(content) { /** * Creates contextual fragment * + * @public * @param {Element} node - DOM node * @param {string} template - HTML template * @return {DocumentFragment} Document fragment @@ -232,6 +243,7 @@ export function createFragment(node, template) { /** * Inserts template string into DOM node, before beforeNode. If beforeNode is null, inserts at end of child nodes * + * @public * @param {Element} node - DOM node * @param {string} template html template * @param {Element|void} beforeNode - DOM node @@ -244,6 +256,7 @@ export function insertTemplate(node, template, beforeNode = null) { /** * Create