fix merge conflict for #1634

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
@@ -516,6 +516,7 @@
 
 		// Cache references to elements
 		dom.controls = document.querySelector( '.reveal .controls' );
+		dom.theme = document.querySelector( '#theme' );
 
 		dom.wrapper.setAttribute( 'role', 'application' );
 
@@ -534,6 +535,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() {
 
@@ -543,7 +546,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' );
@@ -738,6 +741,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 ) {
 
@@ -824,6 +834,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 ) {
 
@@ -941,6 +952,8 @@
 	/**
 	 * Applies the configuration settings from the config
 	 * object. May be called multiple times.
+	 *
+	 * @param {object} options
 	 */
 	function configure( options ) {
 
@@ -1174,6 +1187,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 ) {
 
@@ -1185,6 +1201,9 @@
 
 	/**
 	 * Converts the target object to an array.
+	 *
+	 * @param {object} o
+	 * @return {object[]}
 	 */
 	function toArray( o ) {
 
@@ -1194,6 +1213,9 @@
 
 	/**
 	 * Utility for deserializing a value.
+	 *
+	 * @param {*} value
+	 * @return {*}
 	 */
 	function deserialize( value ) {
 
@@ -1212,8 +1234,10 @@
 	 * Measures the distance in pixels between point a
 	 * and point b.
 	 *
-	 * @param {Object} a point with x/y properties
+	 * @param {object} a point with x/y properties
-	 * @param {Object} b point with x/y properties
+	 * @param {object} b point with x/y properties
+	 *
+	 * @return {number}
 	 */
 	function distanceBetween( a, b ) {
 
@@ -1226,6 +1250,9 @@
 
 	/**
 	 * Applies a CSS transform to the target element.
+	 *
+	 * @param {HTMLElement} element
+	 * @param {string} transform
 	 */
 	function transformElement( element, transform ) {
 
@@ -1240,6 +1267,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 ) {
 
@@ -1259,6 +1288,8 @@
 
 	/**
 	 * Injects the given CSS styles into the DOM.
+	 *
+	 * @param {string} value
 	 */
 	function injectStyleSheet( value ) {
 
@@ -1313,11 +1344,17 @@
 	/**
 	 * Converts various color input formats to an {r:0,g:0,b:0} object.
 	 *
-	 * @param {String} color The string representation of a color,
+	 * @param {string} color The string representation of a color
-	 * the following formats are supported:
+	 * @example
-	 * - #000
+	 * colorToRgb('#000');
-	 * - #000000
+	 * @example
-	 * - rgb(0,0,0)
+	 * 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 ) {
 
@@ -1367,7 +1404,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 ) {
 
@@ -1386,6 +1424,9 @@
 	 * target element.
 	 *
 	 * remaining height = [ configured parent height ] - [ current parent height ]
+	 * 
+	 * @param {HTMLElement} element
+	 * @param {number} [height]
 	 */
 	function getRemainingHeight( element, height ) {
 
@@ -1508,6 +1549,8 @@
 
 	/**
 	 * Bind preview frame links.
+	 *
+	 * @param {string} [selector=a] - selector for anchors
 	 */
 	function enablePreviewLinks( selector ) {
 
@@ -1538,6 +1581,8 @@
 
 	/**
 	 * Opens a preview window for the target URL.
+	 *
+	 * @param {string} url - url for preview iframe src
 	 */
 	function showPreview( url ) {
 
@@ -1579,7 +1624,7 @@
 	}
 
 	/**
-	 * Opens a overlay window with help material.
+	 * Opens an overlay window with help material.
 	 */
 	function showHelp() {
 
@@ -1727,6 +1772,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 ) {
 
@@ -1760,6 +1808,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 ) {
 
@@ -1797,7 +1848,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 ) {
 
@@ -1998,7 +2049,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.
 	 */
@@ -2029,8 +2080,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 ) {
 
@@ -2115,6 +2167,8 @@
 
 	/**
 	 * Checks if we are currently in the paused mode.
+	 *
+	 * @return {Boolean}
 	 */
 	function isPaused() {
 
@@ -2125,7 +2179,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.
 	 */
 
@@ -2143,6 +2197,8 @@
 
 	/**
 	 * Checks if the auto slide mode is currently on.
+	 *
+	 * @return {Boolean}
 	 */
 	function isAutoSliding() {
 
@@ -2155,11 +2211,11 @@
 	 * slide which matches the specified horizontal and vertical
 	 * indices.
 	 *
-	 * @param {int} h Horizontal index of the target slide
+	 * @param {number} [h=indexh] Horizontal index of the target slide
-	 * @param {int} v Vertical index of the target slide
+	 * @param {number} [v=indexv] Vertical index of the target slide
-	 * @param {int} f Optional index of a fragment within the
+	 * @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 ) {
 
@@ -2416,12 +2472,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.
 	 */
@@ -2604,10 +2660,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() {
 
@@ -2679,6 +2735,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 ) {
 
@@ -2750,7 +2811,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 ) {
@@ -2925,7 +2986,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';
 
@@ -2937,6 +2998,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 ) {
 
@@ -3025,6 +3088,8 @@
 	/**
 	 * Called when the given slide is moved outside of the
 	 * configured view distance.
+	 *
+	 * @param {HTMLElement} slide
 	 */
 	function hideSlide( slide ) {
 
@@ -3043,7 +3108,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() {
 
@@ -3072,7 +3137,7 @@
 	 * Returns an object describing the available fragment
 	 * directions.
 	 *
-	 * @return {Object} two boolean properties: prev/next
+	 * @return {{prev: boolean, next: boolean}}
 	 */
 	function availableFragments() {
 
@@ -3118,6 +3183,8 @@
 	/**
 	 * Start playback of any embedded content inside of
 	 * the given element.
+	 *
+	 * @param {HTMLElement} slide
 	 */
 	function startEmbeddedContent( element ) {
 
@@ -3167,7 +3234,9 @@
 
 	/**
 	 * "Starts" the content of an embedded iframe using the
-	 * postmessage API.
+	 * postMessage API.
+	 *
+	 * @param {object} event - postMessage API event
 	 */
 	function startEmbeddedIframe( event ) {
 
@@ -3195,6 +3264,8 @@
 	/**
 	 * Stop playback of any embedded content inside of
 	 * the targeted slide.
+	 *
+	 * @param {HTMLElement} slide
 	 */
 	function stopEmbeddedContent( slide ) {
 
@@ -3240,6 +3311,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() {
 
@@ -3284,6 +3357,8 @@
 	/**
 	 * Returns a value ranging from 0-1 that represents
 	 * how far into the presentation we have navigated.
+	 *
+	 * @return {number}
 	 */
 	function getProgress() {
 
@@ -3317,6 +3392,8 @@
 	/**
 	 * Checks if this presentation is running inside of the
 	 * speaker notes window.
+	 *
+	 * @return {boolean}
 	 */
 	function isSpeakerNotes() {
 
@@ -3372,7 +3449,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 ) {
@@ -3410,16 +3487,15 @@
 		}
 
 	}
-
 	/**
-	 * Retrieves the h/v location of the current, or specified,
+	 * Retrieves the h/v location and fragment of the current,
-	 * slide.
+	 * 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 ) {
 
@@ -3467,6 +3543,8 @@
 
 	/**
 	 * Retrieves the total number of slides in this presentation.
+	 *
+	 * @return {number}
 	 */
 	function getTotalSlides() {
 
@@ -3476,6 +3554,8 @@
 
 	/**
 	 * Returns the slide element matching the specified index.
+	 *
+	 * @return {HTMLElement}
 	 */
 	function getSlide( x, y ) {
 
@@ -3495,6 +3575,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 ) {
 
@@ -3525,6 +3609,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 ) {
 
@@ -3550,6 +3637,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() {
 
@@ -3568,7 +3657,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 ) {
 
@@ -3602,6 +3692,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 ) {
 
@@ -3653,12 +3746,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 ) {
@@ -3741,7 +3834,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() {
@@ -3753,7 +3846,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() {
@@ -3995,6 +4088,8 @@
 	/**
 	 * Called by all event handlers that are based on user
 	 * input.
+	 *
+	 * @param {object} [event]
 	 */
 	function onUserInput( event ) {
 
@@ -4006,6 +4101,8 @@
 
 	/**
 	 * Handler for the document level 'keypress' event.
+	 *
+	 * @param {object} event
 	 */
 	function onDocumentKeyPress( event ) {
 
@@ -4023,6 +4120,8 @@
 
 	/**
 	 * Handler for the document level 'keydown' event.
+	 *
+	 * @param {object} event
 	 */
 	function onDocumentKeyDown( event ) {
 
@@ -4158,6 +4257,8 @@
 	/**
 	 * Handler for the 'touchstart' event, enables support for
 	 * swipe and pinch gestures.
+	 *
+	 * @param {object} event
 	 */
 	function onTouchStart( event ) {
 
@@ -4183,6 +4284,8 @@
 
 	/**
 	 * Handler for the 'touchmove' event.
+	 *
+	 * @param {object} event
 	 */
 	function onTouchMove( event ) {
 
@@ -4272,6 +4375,8 @@
 
 	/**
 	 * Handler for the 'touchend' event.
+	 *
+	 * @param {object} event
 	 */
 	function onTouchEnd( event ) {
 
@@ -4281,6 +4386,8 @@
 
 	/**
 	 * Convert pointer down to touch start.
+	 *
+	 * @param {object} event
 	 */
 	function onPointerDown( event ) {
 
@@ -4293,6 +4400,8 @@
 
 	/**
 	 * Convert pointer move to touch move.
+	 *
+	 * @param {object} event
 	 */
 	function onPointerMove( event ) {
 
@@ -4305,6 +4414,8 @@
 
 	/**
 	 * Convert pointer up to touch end.
+	 *
+	 * @param {object} event
 	 */
 	function onPointerUp( event ) {
 
@@ -4318,6 +4429,8 @@
 	/**
 	 * Handles mouse wheel scrolling, throttled to avoid skipping
 	 * multiple slides.
+	 *
+	 * @param {object} event
 	 */
 	function onDocumentMouseScroll( event ) {
 
@@ -4342,6 +4455,8 @@
 	 * closest approximate horizontal slide using this equation:
 	 *
 	 * ( clickX / presentationWidth ) * numberOfSlides
+	 *
+	 * @param {object} event
 	 */
 	function onProgressClicked( event ) {
 
@@ -4372,6 +4487,8 @@
 
 	/**
 	 * Handler for the window level 'hashchange' event.
+	 *
+	 * @param {object} [event]
 	 */
 	function onWindowHashChange( event ) {
 
@@ -4381,6 +4498,8 @@
 
 	/**
 	 * Handler for the window level 'resize' event.
+	 *
+	 * @param {object} [event]
 	 */
 	function onWindowResize( event ) {
 
@@ -4390,6 +4509,8 @@
 
 	/**
 	 * Handle for the window level 'visibilitychange' event.
+	 *
+	 * @param {object} [event]
 	 */
 	function onPageVisibilityChange( event ) {
 
@@ -4411,6 +4532,8 @@
 
 	/**
 	 * Invoked when a slide is and we're in the overview.
+	 *
+	 * @param {object} event
 	 */
 	function onOverviewSlideClicked( event ) {
 
@@ -4444,6 +4567,8 @@
 	/**
 	 * Handles clicks on links that are set to preview in the
 	 * iframe overlay.
+	 *
+	 * @param {object} event
 	 */
 	function onPreviewLinkClicked( event ) {
 
@@ -4459,6 +4584,8 @@
 
 	/**
 	 * Handles click on the auto-sliding controls element.
+	 *
+	 * @param {object} [event]
 	 */
 	function onAutoSlidePlayerClick( event ) {
 
@@ -4490,7 +4617,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
 	 */
@@ -4527,6 +4654,9 @@
 
 	}
 
+	/**
+	 * @param value
+	 */
 	Playback.prototype.setPlaying = function( value ) {
 
 		var wasPlaying = this.playing;