Common libraries in src/lib

DOCUMENTATION.md

@@ -229,6 +229,31 @@ rootElement.addEventListener( "impress:init", function() {
 impress().init();
 ```
 
+#### .tear()
+
+Resets the DOM to its original state, as it was before `init()` was called.
+
+This can be used to "unload" impress.js. A particular use case for this is, if you want to do
+dynamic changes to the presentation, you can do a teardown, apply changes, then call `init()`
+again. (In most cases, this will not cause flickering or other visible effects to the user,
+beyond the intended dynamic changes.)
+
+**Example:**
+
+```JavaScript
+impress().tear();
+```
+
+**Example:**
+
+```JavaScript
+var rootElement = document.getElementById( "impress" );
+rootElement.addEventListener( "impress:init", function() {
+  console.log( "Impress init" );
+});
+impress().init();
+```
+
 #### .next()
 
 Navigates to the next step of the presentation using the [`goto()` function](#impressgotostepindexstepelementidstepelement-duration).

src/lib/README.md

@@ -83,11 +83,11 @@ Putting all of the above together, a skeleton library file will look like:
             var instanceVar = {};
 
             // LIBRARY FUNCTIONS
-            var libararyFunction1 = function () {
+            var libraryFunction1 = function () {
                 /* ... */
             };
 
-            var libararyFunction2 = function () {
+            var libraryFunction2 = function () {
                 /* ... */
             };
 

src/lib/gc.js

@@ -31,34 +31,43 @@
         recordStartingState( rootId );
 
         // LIBRARY FUNCTIONS
-        // Below are definitions of the library functions we return at the end
+        // Definitions of the library functions we return as an object at the end
+
+        // `pushElement` adds a DOM element to the gc stack
         var pushElement = function( element ) {
             elementList.push( element );
         };
 
-        // Convenience wrapper that combines DOM appendChild with gc.pushElement
+        // `appendChild` is a convenience wrapper that combines DOM appendChild with gc.pushElement
         var appendChild = function( parent, element ) {
             parent.appendChild( element );
             pushElement( element );
         };
 
+        // `pushEventListener` adds an event listener to the gc stack
         var pushEventListener = function( target, type, listenerFunction ) {
             eventListenerList.push( { target:target, type:type, listener:listenerFunction } );
         };
 
-        // Convenience wrapper that combines DOM addEventListener with gc.pushEventListener
+        // `addEventListener` combines DOM addEventListener with gc.pushEventListener
         var addEventListener = function( target, type, listenerFunction ) {
             target.addEventListener( type, listenerFunction );
             pushEventListener( target, type, listenerFunction );
         };
 
-        // If the above utilities are not enough, plugins can add their own callback function
-        // to do arbitrary things.
+        // `addCallback` If the above utilities are not enough, plugins can add their own callback
+        // function to do arbitrary things.
         var addCallback = function( callback ) {
             callbackList.push( callback );
         };
         addCallback( function( rootId ) { resetStartingState( rootId ); } );
 
+        // `teardown` will
+        // - execute all callbacks in LIFO order
+        // - call `removeChild` on all DOM elements in LIFO order
+        // - call `removeEventListener` on all event listeners in LIFO order
+        // The goal of a teardown is to return to the same state that the DOM was before
+        // `impress().init()` was called.
         var teardown = function() {
 
             // Execute the callbacks in LIFO order