aboutsummaryrefslogtreecommitdiff
path: root/js
diff options
context:
space:
mode:
authorCharles Grigg <charles.grigg2@gmail.com>2016-06-29 23:10:55 -0400
committerCharles Grigg <charles.grigg2@gmail.com>2016-06-29 23:10:55 -0400
commit59f3395c7f7a01268857040c788c2ca98c9b0dd9 (patch)
tree5de97f5bc015ccf67f1ebd7e0b20c3f451848268 /js
parent541bcf212314e368bffa815401497bb94d2acf0e (diff)
downloadfosdem-2018-presentation-59f3395c7f7a01268857040c788c2ca98c9b0dd9.tar
fosdem-2018-presentation-59f3395c7f7a01268857040c788c2ca98c9b0dd9.tar.gz
Update JSDocs and fix typos
Diffstat (limited to 'js')
-rw-r--r--js/reveal.js216
1 files 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: <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;