From 59f3395c7f7a01268857040c788c2ca98c9b0dd9 Mon Sep 17 00:00:00 2001 From: Charles Grigg Date: Wed, 29 Jun 2016 23:10:55 -0400 Subject: [PATCH] Update JSDocs and fix typos --- js/reveal.js | 216 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 173 insertions(+), 43 deletions(-) diff --git a/js/reveal.js b/js/reveal.js index 3f003d9..b591735 100644 --- a/js/reveal.js +++ b/js/reveal.js @@ -92,7 +92,7 @@ // i.e. contained within a limited portion of the screen embedded: false, - // Flags if we should show a help overlay when the questionmark + // Flags if we should show a help overlay when the question-mark // key is pressed help: true, @@ -131,7 +131,7 @@ // Dispatches all reveal.js events to the parent window through postMessage postMessageEvents: false, - // Focuses body when page changes visiblity to ensure keyboard shortcuts work + // Focuses body when page changes visibility to ensure keyboard shortcuts work focusBodyOnPageVisibilityChange: true, // Transition style @@ -514,6 +514,7 @@ // Cache references to elements dom.controls = document.querySelector( '.reveal .controls' ); + dom.theme = document.querySelector( '#theme' ); dom.wrapper.setAttribute( 'role', 'application' ); @@ -532,6 +533,8 @@ * Creates a hidden div with role aria-live to announce the * current slide content. Hide the div off-screen to make it * available only to Assistive Technologies. + * + * @return {HTMLElement} */ function createStatusDiv() { @@ -541,7 +544,7 @@ statusDiv.style.position = 'absolute'; statusDiv.style.height = '1px'; statusDiv.style.width = '1px'; - statusDiv.style.overflow ='hidden'; + statusDiv.style.overflow = 'hidden'; statusDiv.style.clip = 'rect( 1px, 1px, 1px, 1px )'; statusDiv.setAttribute( 'id', 'aria-status-div' ); statusDiv.setAttribute( 'aria-live', 'polite' ); @@ -704,6 +707,13 @@ * Creates an HTML element and returns a reference to it. * If the element already exists the existing instance will * be returned. + * + * @param {HTMLElement} container + * @param {string} tagname + * @param {string} classname + * @param {string} innerHTML + * + * @return {HTMLElement} */ function createSingletonNode( container, tagname, classname, innerHTML ) { @@ -790,6 +800,7 @@ * @param {HTMLElement} slide * @param {HTMLElement} container The element that the background * should be appended to + * @return {HTMLElement} New background div */ function createBackground( slide, container ) { @@ -907,6 +918,8 @@ /** * Applies the configuration settings from the config * object. May be called multiple times. + * + * @param {object} options */ function configure( options ) { @@ -1140,6 +1153,9 @@ /** * Extend object a with the properties of object b. * If there's a conflict, object b takes precedence. + * + * @param {object} a + * @param {object} b */ function extend( a, b ) { @@ -1151,6 +1167,9 @@ /** * Converts the target object to an array. + * + * @param {object} o + * @return {object[]} */ function toArray( o ) { @@ -1160,6 +1179,9 @@ /** * Utility for deserializing a value. + * + * @param {*} value + * @return {*} */ function deserialize( value ) { @@ -1178,8 +1200,10 @@ * Measures the distance in pixels between point a * and point b. * - * @param {Object} a point with x/y properties - * @param {Object} b point with x/y properties + * @param {object} a point with x/y properties + * @param {object} b point with x/y properties + * + * @return {number} */ function distanceBetween( a, b ) { @@ -1192,6 +1216,9 @@ /** * Applies a CSS transform to the target element. + * + * @param {HTMLElement} element + * @param {string} transform */ function transformElement( element, transform ) { @@ -1206,6 +1233,8 @@ * Applies CSS transforms to the slides container. The container * is transformed from two separate sources: layout and the overview * mode. + * + * @param {object} transforms */ function transformSlides( transforms ) { @@ -1225,6 +1254,8 @@ /** * Injects the given CSS styles into the DOM. + * + * @param {string} value */ function injectStyleSheet( value ) { @@ -1243,11 +1274,17 @@ /** * Converts various color input formats to an {r:0,g:0,b:0} object. * - * @param {String} color The string representation of a color, - * the following formats are supported: - * - #000 - * - #000000 - * - rgb(0,0,0) + * @param {string} color The string representation of a color + * @example + * colorToRgb('#000'); + * @example + * colorToRgb('#000000'); + * @example + * colorToRgb('rgb(0,0,0)'); + * @example + * colorToRgb('rgba(0,0,0)'); + * + * @return {{r: number, g: number, b: number, [a]: number}|null} */ function colorToRgb( color ) { @@ -1297,7 +1334,8 @@ /** * Calculates brightness on a scale of 0-255. * - * @param color See colorStringToRgb for supported formats. + * @param {string} color See colorToRgb for supported formats. + * @see {@link colorToRgb} */ function colorBrightness( color ) { @@ -1316,6 +1354,9 @@ * target element. * * remaining height = [ configured parent height ] - [ current parent height ] + * + * @param {HTMLElement} element + * @param {number} [height] */ function getRemainingHeight( element, height ) { @@ -1438,6 +1479,8 @@ /** * Bind preview frame links. + * + * @param {string} [selector=a] - selector for anchors */ function enablePreviewLinks( selector ) { @@ -1468,6 +1511,8 @@ /** * Opens a preview window for the target URL. + * + * @param {string} url - url for preview iframe src */ function showPreview( url ) { @@ -1509,7 +1554,7 @@ } /** - * Opens a overlay window with help material. + * Opens an overlay window with help material. */ function showHelp() { @@ -1657,6 +1702,9 @@ /** * Applies layout logic to the contents of all slides in * the presentation. + * + * @param {string|number} width + * @param {string|number} height */ function layoutSlideContents( width, height ) { @@ -1690,6 +1738,9 @@ * Calculates the computed pixel size of our slides. These * values are based on the width and height configuration * options. + * + * @param {number} [presentationWidth=dom.wrapper.offsetWidth] + * @param {number} [presentationHeight=dom.wrapper.offsetHeight] */ function getComputedSlideSize( presentationWidth, presentationHeight ) { @@ -1727,7 +1778,7 @@ * from the stack. * * @param {HTMLElement} stack The vertical stack element - * @param {int} v Index to memorize + * @param {string|number} [v=0] Index to memorize */ function setPreviousVerticalIndex( stack, v ) { @@ -1928,7 +1979,7 @@ /** * Toggles the slide overview mode on and off. * - * @param {Boolean} override Optional flag which overrides the + * @param {Boolean} [override] Flag which overrides the * toggle logic and forcibly sets the desired state. True means * overview is open, false means it's closed. */ @@ -1959,8 +2010,9 @@ * Checks if the current or specified slide is vertical * (nested within another slide). * - * @param {HTMLElement} slide [optional] The slide to check + * @param {HTMLElement} [slide=currentSlide] The slide to check * orientation of + * @return {Boolean} */ function isVerticalSlide( slide ) { @@ -2045,6 +2097,8 @@ /** * Checks if we are currently in the paused mode. + * + * @return {Boolean} */ function isPaused() { @@ -2055,7 +2109,7 @@ /** * Toggles the auto slide mode on and off. * - * @param {Boolean} override Optional flag which sets the desired state. + * @param {Boolean} [override] Flag which sets the desired state. * True means autoplay starts, false means it stops. */ @@ -2073,6 +2127,8 @@ /** * Checks if the auto slide mode is currently on. + * + * @return {Boolean} */ function isAutoSliding() { @@ -2085,11 +2141,11 @@ * slide which matches the specified horizontal and vertical * indices. * - * @param {int} h Horizontal index of the target slide - * @param {int} v Vertical index of the target slide - * @param {int} f Optional index of a fragment within the + * @param {number} [h=indexh] Horizontal index of the target slide + * @param {number} [v=indexv] Vertical index of the target slide + * @param {number} [f] Index of a fragment within the * target slide to activate - * @param {int} o Optional origin for use in multimaster environments + * @param {number} [o] Origin for use in multimaster environments */ function slide( h, v, f, o ) { @@ -2343,12 +2399,12 @@ * Updates one dimension of slides by showing the slide * with the specified index. * - * @param {String} selector A CSS selector that will fetch + * @param {string} selector A CSS selector that will fetch * the group of slides we are working with - * @param {Number} index The index of the slide that should be + * @param {number} index The index of the slide that should be * shown * - * @return {Number} The index of the slide that is now shown, + * @return {number} The index of the slide that is now shown, * might differ from the passed in index if it was out of * bounds. */ @@ -2531,10 +2587,10 @@ } /** - * Pick up notes from the current slide and display tham + * Pick up notes from the current slide and display them * to the viewer. * - * @see `showNotes` config value + * @see {@link config.showNotes} */ function updateNotes() { @@ -2606,6 +2662,11 @@ /** * Applies HTML formatting to a slide number before it's * written to the DOM. + * + * @param {number} a Current slide + * @param {string} delimiter Character to separate slide numbers + * @param {(number|*)} b Total slides + * @return {string} HTML string fragment */ function formatSlideNumber( a, delimiter, b ) { @@ -2677,7 +2738,7 @@ * Updates the background elements to reflect the current * slide. * - * @param {Boolean} includeAll If true, the backgrounds of + * @param {boolean} includeAll If true, the backgrounds of * all vertical slides (not just the present) will be updated. */ function updateBackground( includeAll ) { @@ -2852,7 +2913,7 @@ verticalOffsetMultiplier = ( backgroundHeight - slideHeight ) / ( verticalSlideCount-1 ); } - verticalOffset = verticalSlideCount > 0 ? verticalOffsetMultiplier * indexv * 1 : 0; + verticalOffset = verticalSlideCount > 0 ? verticalOffsetMultiplier * indexv : 0; dom.background.style.backgroundPosition = horizontalOffset + 'px ' + -verticalOffset + 'px'; @@ -2864,6 +2925,8 @@ * Called when the given slide is within the configured view * distance. Shows the slide element and loads any content * that is set to load lazily (data-src). + * + * @param {HTMLElement} slide Slide to show */ function showSlide( slide ) { @@ -2952,6 +3015,8 @@ /** * Called when the given slide is moved outside of the * configured view distance. + * + * @param {HTMLElement} slide */ function hideSlide( slide ) { @@ -2970,7 +3035,7 @@ /** * Determine what available routes there are for navigation. * - * @return {Object} containing four booleans: left/right/up/down + * @return {{left: boolean, right: boolean, up: boolean, down: boolean}} */ function availableRoutes() { @@ -2999,7 +3064,7 @@ * Returns an object describing the available fragment * directions. * - * @return {Object} two boolean properties: prev/next + * @return {{prev: boolean, next: boolean}} */ function availableFragments() { @@ -3045,6 +3110,8 @@ /** * Start playback of any embedded content inside of * the targeted slide. + * + * @param {HTMLElement} slide */ function startEmbeddedContent( slide ) { @@ -3082,7 +3149,9 @@ /** * "Starts" the content of an embedded iframe using the - * postmessage API. + * postMessage API. + * + * @param {object} event - postMessage API event */ function startEmbeddedIframe( event ) { @@ -3106,6 +3175,8 @@ /** * Stop playback of any embedded content inside of * the targeted slide. + * + * @param {HTMLElement} slide */ function stopEmbeddedContent( slide ) { @@ -3151,6 +3222,8 @@ /** * Returns the number of past slides. This can be used as a global * flattened index for slides. + * + * @return {number} Past slide count */ function getSlidePastCount() { @@ -3195,6 +3268,8 @@ /** * Returns a value ranging from 0-1 that represents * how far into the presentation we have navigated. + * + * @return {number} */ function getProgress() { @@ -3228,6 +3303,8 @@ /** * Checks if this presentation is running inside of the * speaker notes window. + * + * @return {boolean} */ function isSpeakerNotes() { @@ -3283,7 +3360,7 @@ * Updates the page URL (hash) to reflect the current * state. * - * @param {Number} delay The time in ms to wait before + * @param {number} delay The time in ms to wait before * writing the hash */ function writeURL( delay ) { @@ -3321,16 +3398,15 @@ } } - /** - * Retrieves the h/v location of the current, or specified, - * slide. + * Retrieves the h/v location and fragment of the current, + * or specified, slide. * - * @param {HTMLElement} slide If specified, the returned + * @param {HTMLElement} [slide] If specified, the returned * index will be for this slide rather than the currently * active one * - * @return {Object} { h: , v: , f: } + * @return {{h: number, v: number, f: number}} */ function getIndices( slide ) { @@ -3378,6 +3454,8 @@ /** * Retrieves the total number of slides in this presentation. + * + * @return {number} */ function getTotalSlides() { @@ -3387,6 +3465,8 @@ /** * Returns the slide element matching the specified index. + * + * @return {HTMLElement} */ function getSlide( x, y ) { @@ -3406,6 +3486,10 @@ * All slides, even the ones with no background properties * defined, have a background element so as long as the * index is valid an element will be returned. + * + * @param {number} x Horizontal background index + * @param {number} y Vertical background index + * @return {(HTMLElement[]|*)} */ function getSlideBackground( x, y ) { @@ -3436,6 +3520,9 @@ * defined in two ways: * 1. As a data-notes attribute on the slide
* 2. As an