From bff4f64d571f1fac88446683deda769c426abe09 Mon Sep 17 00:00:00 2001 From: Jeremy Likness Date: Mon, 25 Nov 2019 11:34:32 -0800 Subject: [PATCH] Update documentation --- js/animator.js | 21 +++++++++++++++------ js/controls.js | 13 ++++++++++--- js/keyhandler.js | 5 +++-- js/navigator.js | 35 ++++++++++++++++++++++++----------- js/router.js | 14 ++++++++++---- js/slide.js | 35 +++++++++++++++++++++++++++-------- 6 files changed, 89 insertions(+), 34 deletions(-) diff --git a/js/animator.js b/js/animator.js index f4f973f..4ec52f6 100644 --- a/js/animator.js +++ b/js/animator.js @@ -2,23 +2,32 @@ /** * Handles animations and transitions - * @property {boolean} _transitioning True when animation in effect - * @property {string} _begin The beginning animation class - * @property {string} _end The ending animation class */ export class Animator { /** * Create an instance of the animation helper */ constructor() { + /** + * True when an animation is in effect + * @type {boolean} + */ this._transitioning = false; + /** + * The name of the beginning animation + * @type {string} + */ this._begin = null; + /** + * The name of the ending animation + * @type {string} + */ this._end = null; } /** - * True when animation in effect - * @returns {boolean} + * True when animation is in effect + * @returns {boolean} True if animation is happening */ get transitioning() { return this._transitioning; @@ -26,7 +35,7 @@ export class Animator { /** * True when ready to complete second part of animation - * @returns {boolean} + * @returns {boolean} True if there is a second animation to fire */ get animationReady() { return !!this._end; diff --git a/js/controls.js b/js/controls.js index 8f3b2da..64a8613 100644 --- a/js/controls.js +++ b/js/controls.js @@ -13,6 +13,7 @@ import { Navigator } from "./navigator.js" /** * Custom element that renders controls to navigate the deck + * @extends {HTMLElement} */ export class Controls extends HTMLElement { @@ -21,9 +22,15 @@ export class Controls extends HTMLElement { */ constructor() { super(); - /** @type {CustomRef} */ + /** + * The internal reference list of controls + * @type {CustomRef} + */ this._controlRef = null; - /** @type {Navigator} */ + /** + * The related Navigator instance (deck) to control + * @type {Navigator} + */ this._deck = null; } @@ -53,7 +60,7 @@ export class Controls extends HTMLElement { /** * Get the list of attributes to watch - * @returns {string[]} + * @returns {string[]} List of observable attributes */ static get observedAttributes() { return ["deck"]; diff --git a/js/keyhandler.js b/js/keyhandler.js index 3ff4fa1..06e1e94 100644 --- a/js/keyhandler.js +++ b/js/keyhandler.js @@ -4,6 +4,7 @@ import { Navigator } from "./navigator.js" /** * Custom element to handle key press + * @extends {HTMLElement} */ export class KeyHandler extends HTMLElement { @@ -12,8 +13,8 @@ export class KeyHandler extends HTMLElement { */ constructor() { super(); - /** - * The related Navigator element + /** + * The related Navigator instance (deck) to handle key press events for * @type {Navigator} */ this._deck = null; diff --git a/js/navigator.js b/js/navigator.js index 5f47ce5..b23c0e8 100644 --- a/js/navigator.js +++ b/js/navigator.js @@ -7,10 +7,7 @@ import { Animator } from "./animator.js" /** * The main class that handles rendering the slide decks - * @property {Animator} _animator Animation helper - * @property {Router} _router Routing helper - * @property {string} _route The current route - * @property {CustomEvent} slidesChangedEvent Event fired when slide changes + * @extends {HTMLElement} */ export class Navigator extends HTMLElement { @@ -19,9 +16,25 @@ export class Navigator extends HTMLElement { */ constructor() { super(); + /** + * The related animation control + * @type {Animator} + */ this._animator = new Animator(); + /** + * The related router control + * @type {Router} + */ this._router = new Router(); + /** + * The last known route + * @type {string} + */ this._route = this._router.getRoute(); + /** + * Custom event raised when the current slide changes + * @type {CustomEvent} + */ this.slidesChangedEvent = new CustomEvent("slideschanged", { bubbles: true, cancelable: false @@ -39,7 +52,7 @@ export class Navigator extends HTMLElement { /** * Get the list of observed attributes - * @returns {string[]} + * @returns {string[]} The list of attributes to watch */ static get observedAttributes() { return ["start"]; @@ -68,7 +81,7 @@ export class Navigator extends HTMLElement { /** * Current slide index - * @returns {number} + * @returns {number} The current slide index */ get currentIndex() { return this._currentIndex; @@ -76,7 +89,7 @@ export class Navigator extends HTMLElement { /** * Current slide - * @returns {Slide} + * @returns {Slide} The current slide */ get currentSlide() { return this._slides ? this._slides[this._currentIndex] : null; @@ -84,7 +97,7 @@ export class Navigator extends HTMLElement { /** * Total number of slides - * @returns {number} + * @returns {number} The total slide count */ get totalSlides() { return this._slides ? this._slides.length : 0; @@ -92,7 +105,7 @@ export class Navigator extends HTMLElement { /** * True if a previous slide exists - * @returns {boolean} + * @returns {boolean} True if a previous slide exists */ get hasPrevious() { return this._currentIndex > 0; @@ -100,7 +113,7 @@ export class Navigator extends HTMLElement { /** * True if a next slide exists - * @returns {boolean} + * @returns {boolean} True if a subsequent slide exists */ get hasNext() { return this._currentIndex < (this.totalSlides - 1); @@ -108,7 +121,7 @@ export class Navigator extends HTMLElement { /** * Main slide navigation: jump to specific slide - * @param {number} slideIdx + * @param {number} slideIdx The index of the slide to navigate to */ jumpTo(slideIdx) { if (this._animator.transitioning) { diff --git a/js/router.js b/js/router.js index 81e8c2c..770bb4b 100644 --- a/js/router.js +++ b/js/router.js @@ -5,20 +5,26 @@ */ export class Router { + /** + * Create a new Router instance + */ constructor() { - /** - * @property {HTMLDivElement} _eventSource Arbitrary DIV used to generate events + /** + * Arbitrary element to source events + * @type {HTMLDivElement} */ this._eventSource = document.createElement("div"); /** - * @property {CustomEvent} _routeChanged Custom event raised when the route changes + * Custom event raised when the route changes + * @type {CustomEvent} */ this._routeChanged = new CustomEvent("routechanged", { bubbles: true, cancelable: false }); /** - * @property {string} _route The current route + * The current route + * @type {string} */ this._route = null; window.addEventListener("popstate", () => { diff --git a/js/slide.js b/js/slide.js index 42e7299..1aceb05 100644 --- a/js/slide.js +++ b/js/slide.js @@ -1,5 +1,7 @@ // @ts-check -/** Represents a slide */ +/** + * Represents a slide + * */ export class Slide { /** @@ -7,16 +9,29 @@ export class Slide { * @param {string} text - The content of the slide */ constructor(text) { - /** @property {string} _text - internal text representation */ + /** + * Internal text representation of the slide + * @type {string} + */ this._text = text; - /** @property {HTMLDivElement} _html - host div */ + /** + * The HTML DOM hosting the slide contents + * @type {HTMLDivElement} + */ this._html = document.createElement('div'); this._html.innerHTML = text; - /** @property {string} _title - title of the slide */ + /** + * The title of the slide + * @type {string} + */ this._title = this._html.querySelectorAll("title")[0].innerText; /** @type{NodeListOf} */ const transition = (this._html.querySelectorAll("transition")); if (transition.length) { + /** + * The name of the animation to use for transitions + * @type {string} + */ this._transition = transition[0].innerText; } else { @@ -25,6 +40,10 @@ export class Slide { /** @type{NodeListOf} */ const hasNext = this._html.querySelectorAll("nextslide"); if (hasNext.length > 0) { + /** + * The name of the next slide to load + * @type {string} + */ this._nextSlideName = hasNext[0].innerText; } else { @@ -34,7 +53,7 @@ export class Slide { /** * The slide transition - * @return{string} The transition name + * @returns {string} The transition name */ get transition() { return this._transition; @@ -42,7 +61,7 @@ export class Slide { /** * The slide title - * @return{string} The slide title + * @returns {string} The slide title */ get title() { return this._title; @@ -50,7 +69,7 @@ export class Slide { /** * The HTML DOM node for the slide - * @return{HTMLDivElement} The HTML content + * @returns {HTMLDivElement} The HTML content */ get html() { return this._html; @@ -58,7 +77,7 @@ export class Slide { /** * The name of the next slide (filename without the .html extension) - * @return{string} The name of the next slide + * @returns {string} The name of the next slide */ get nextSlide() { return this._nextSlideName;