Update JSDocs and fix typos

This commit is contained in:
Charles Grigg 2016-06-29 23:10:55 -04:00
parent 541bcf2123
commit 59f3395c7f
1 changed files with 173 additions and 43 deletions

View File

@ -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: <int>, v: <int>, f: <int> }
* @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 <section>
* 2. As an <aside class="notes"> inside of the slide
*
* @param {HTMLElement} [slide=currentSlide]
* @return {(string|null)}
*/
function getSlideNotes( slide ) {
@ -3461,6 +3548,8 @@
* Retrieves the current state of the presentation as
* an object. This state can then be restored at any
* time.
*
* @return {{indexh: number, indexv: number, indexf: number, paused: boolean, overview: boolean}}
*/
function getState() {
@ -3479,7 +3568,8 @@
/**
* Restores the presentation to the given state.
*
* @param {Object} state As generated by getState()
* @param {object} state As generated by getState()
* @see {@link getState} generates the parameter `state`
*/
function setState( state ) {
@ -3513,6 +3603,9 @@
* attribute to each node if such an attribute is not already present,
* and sets that attribute to an integer value which is the position of
* the fragment within the fragments list.
*
* @param {object[]|*} fragments
* @return {object[]} sorted Sorted array of fragments
*/
function sortFragments( fragments ) {
@ -3564,12 +3657,12 @@
/**
* Navigate to the specified slide fragment.
*
* @param {Number} index The index of the fragment that
* @param {?number} index The index of the fragment that
* should be shown, -1 means all are invisible
* @param {Number} offset Integer offset to apply to the
* @param {number} offset Integer offset to apply to the
* fragment index
*
* @return {Boolean} true if a change was made in any
* @return {boolean} true if a change was made in any
* fragments visibility as part of this call
*/
function navigateFragment( index, offset ) {
@ -3652,7 +3745,7 @@
/**
* Navigate to the next slide fragment.
*
* @return {Boolean} true if there was a next fragment,
* @return {boolean} true if there was a next fragment,
* false otherwise
*/
function nextFragment() {
@ -3664,7 +3757,7 @@
/**
* Navigate to the previous slide fragment.
*
* @return {Boolean} true if there was a previous fragment,
* @return {boolean} true if there was a previous fragment,
* false otherwise
*/
function previousFragment() {
@ -3905,6 +3998,8 @@
/**
* Called by all event handlers that are based on user
* input.
*
* @param {object} [event]
*/
function onUserInput( event ) {
@ -3916,6 +4011,8 @@
/**
* Handler for the document level 'keypress' event.
*
* @param {object} event
*/
function onDocumentKeyPress( event ) {
@ -3933,6 +4030,8 @@
/**
* Handler for the document level 'keydown' event.
*
* @param {object} event
*/
function onDocumentKeyDown( event ) {
@ -4068,6 +4167,8 @@
/**
* Handler for the 'touchstart' event, enables support for
* swipe and pinch gestures.
*
* @param {object} event
*/
function onTouchStart( event ) {
@ -4093,6 +4194,8 @@
/**
* Handler for the 'touchmove' event.
*
* @param {object} event
*/
function onTouchMove( event ) {
@ -4182,6 +4285,8 @@
/**
* Handler for the 'touchend' event.
*
* @param {object} event
*/
function onTouchEnd( event ) {
@ -4191,6 +4296,8 @@
/**
* Convert pointer down to touch start.
*
* @param {object} event
*/
function onPointerDown( event ) {
@ -4203,6 +4310,8 @@
/**
* Convert pointer move to touch move.
*
* @param {object} event
*/
function onPointerMove( event ) {
@ -4215,6 +4324,8 @@
/**
* Convert pointer up to touch end.
*
* @param {object} event
*/
function onPointerUp( event ) {
@ -4228,6 +4339,8 @@
/**
* Handles mouse wheel scrolling, throttled to avoid skipping
* multiple slides.
*
* @param {object} event
*/
function onDocumentMouseScroll( event ) {
@ -4252,6 +4365,8 @@
* closest approximate horizontal slide using this equation:
*
* ( clickX / presentationWidth ) * numberOfSlides
*
* @param {object} event
*/
function onProgressClicked( event ) {
@ -4282,6 +4397,8 @@
/**
* Handler for the window level 'hashchange' event.
*
* @param {object} [event]
*/
function onWindowHashChange( event ) {
@ -4291,6 +4408,8 @@
/**
* Handler for the window level 'resize' event.
*
* @param {object} [event]
*/
function onWindowResize( event ) {
@ -4300,6 +4419,8 @@
/**
* Handle for the window level 'visibilitychange' event.
*
* @param {object} [event]
*/
function onPageVisibilityChange( event ) {
@ -4321,6 +4442,8 @@
/**
* Invoked when a slide is and we're in the overview.
*
* @param {object} event
*/
function onOverviewSlideClicked( event ) {
@ -4354,6 +4477,8 @@
/**
* Handles clicks on links that are set to preview in the
* iframe overlay.
*
* @param {object} event
*/
function onPreviewLinkClicked( event ) {
@ -4369,6 +4494,8 @@
/**
* Handles click on the auto-sliding controls element.
*
* @param {object} [event]
*/
function onAutoSlidePlayerClick( event ) {
@ -4400,7 +4527,7 @@
*
* @param {HTMLElement} container The component will append
* itself to this
* @param {Function} progressCheck A method which will be
* @param {function} progressCheck A method which will be
* called frequently to get the current progress on a range
* of 0-1
*/
@ -4437,6 +4564,9 @@
}
/**
* @param value
*/
Playback.prototype.setPlaying = function( value ) {
var wasPlaying = this.playing;