Update code documentation

2 files changed, 118 insertions, 55 deletions

diff --git a/API.md b/API.md
index a6c7b63..b7babbe 100644
--- a/API.md
+++ b/API.md
@@ -2,59 +2,90 @@
 
 **Functions**
 
-* [once(id)](#once)
-* [removeOnce(id)](#removeOnce)
-* [findOnce(id)](#findOnce)
+* [once([id])](#once)
+* [removeOnce([id])](#removeOnce)
+* [findOnce([id])](#findOnce)
  
 <a name="once"></a>
-#once(id)
+#once([id])
 Filter elements by whether they have not yet been processed.
 
 **Params**
 
-- id `string` - The data id used to determine whether the given elements have already
-  been processed or not.  
+- \[id="once"\] `string` - The data ID used to determine whether the given elements have already
+  been processed or not. Defaults to `"once"`.  
 
-**Returns**:  - jQuery element collection of elements that have now run once by
-  the given id.  
+**Returns**:  - jQuery collection of elements that have now run once by
+  the given ID.  
 **Example**  
-// Change the color to green only once.
-$('p').once('changecolor').css('color', 'green');
+``` javascript
+// The following will change the color of each paragraph to red, just once
+// for the "changecolor" key.
+$('p').once('changecolor').css('color', 'red');
+
+// .once() will return a set of elements that yet to have the once ID
+// associated with them. You can return to the original collection set by
+// using .end().
+$('p')
+  .once("changecolorblue")
+    .css("color", "blue")
+  .end()
+  .css("color", "red");
+
+// To execute a function on the once set, you can use jQuery's each().
+$('div.calendar').once().each(function() {
+  // Since there is no once ID provided here, the key will be "once".
+});
+```
 
 <a name="removeOnce"></a>
-#removeOnce(id)
-Removes the once data from the given elements, based on the given ID.
+#removeOnce([id])
+Removes the once data from elements, based on the given ID.
 
 **Params**
 
-- id `string` - A required string representing the name of the data id which should be used
-  when filtering the elements. This only filters elements that have already
-  been processed by the once function. The id should be the same id that
-  was originally passed to the once() function.  
+- \[id="once"\] `string` - A string representing the name of the data ID which should be used when
+  filtering the elements. This only filters elements that have already been
+  processed by the once function. The ID should be the same ID that was
+  originally passed to the once() function. Defaults to `"once"`.  
 
-**Returns**:  - jQuery element collection of elements that now have their once
-  data removed.  
+**Returns**:  - jQuery collection of elements that were acted upon to remove their
+   once data.  
 **Example**  
-// Remove once data with the "changecolor" ID.
-$('p').removeOnce('changecolor').each(function() {
-  // This function is called for all elements that had their once removed.
+``` javascript
+// Remove once data with the "changecolor" ID. The result set is the
+// elements that had their once data removed.
+$('p').removeOnce("changecolor").css("color", "");
+
+// Any jQuery function can be performed on the result set.
+$("div.calendar").removeOnce().each(function() {
+  // Remove the calendar behavior.
 });
+```
 
 <a name="findOnce"></a>
-#findOnce(id)
+#findOnce([id])
 Filters elements that have already been processed once.
 
 **Params**
 
-- id `string` - A required string representing the name of the data id which should be used
-  when filtering the elements. This only filters elements that have already
+- \[id="once"\] `string` - A string representing the name of the data id which should be used when
+  filtering the elements. This only filters elements that have already
   been processed by the once function. The id should be the same id that
-  was originally passed to the once() function.  
+  was originally passed to the once() function. Defaults to "once".  
 
-**Returns**:  - jQuery element collection of elements that have been run once.  
+**Returns**:  - jQuery collection of elements that have been run once.  
 **Example**  
-// Find all elements that have the changecolor'ed once.
+``` javascript
+// Find all elements that have been changecolor'ed once.
 $('p').findOnce('changecolor').each(function() {
   // This function is called for all elements that has already once'd.
 });
 
+// Find all elements that have been acted on with the default "once" key.
+$('p').findOnce().each(function() {
+  // This function is called for all elements that have been acted on with
+  // a "once" action.
+});
+```
+
diff --git a/jquery.once.js b/jquery.once.js
index 5d27b47..27e7f1b 100644
--- a/jquery.once.js
+++ b/jquery.once.js
@@ -30,14 +30,15 @@
   "use strict";
 
   /**
-   * Ensures that the given id is valid, returning "once" if one is not given.
+   * Ensures that the given ID is valid, returning "once" if one is not given.
    *
-   * @param {string} [id]
-   *   A string representing the id to check. Defaults to "once".
+   * @param {string} [id="once"]
+   *   A string representing the ID to check. Defaults to `"once"`.
    *
-   * @returns The valid id name.
+   * @returns The valid ID name.
    *
-   * @throws Error when an id is provided, but not a string.
+   * @throws Error when an ID is provided, but not a string.
+   * @private
    */
   var checkId = function(id) {
     id = id || "once";
@@ -50,16 +51,33 @@
   /**
    * Filter elements by whether they have not yet been processed.
    *
-   * @param {string} [id]
-   *   The data id used to determine whether the given elements have already
-   *   been processed or not. Defaults to "once".
+   * @param {string} [id="once"]
+   *   The data ID used to determine whether the given elements have already
+   *   been processed or not. Defaults to `"once"`.
    *
-   * @returns jQuery element collection of elements that have now run once by
-   *   the given id.
+   * @returns jQuery collection of elements that have now run once by
+   *   the given ID.
    *
    * @example
-   * // Change the color to green only once.
-   * $('p').once('changecolor').css('color', 'green');
+   * ``` javascript
+   * // The following will change the color of each paragraph to red, just once
+   * // for the "changecolor" key.
+   * $('p').once('changecolor').css('color', 'red');
+   *
+   * // .once() will return a set of elements that yet to have the once ID
+   * // associated with them. You can return to the original collection set by
+   * // using .end().
+   * $('p')
+   *   .once("changecolorblue")
+   *     .css("color", "blue")
+   *   .end()
+   *   .css("color", "red");
+   *
+   * // To execute a function on the once set, you can use jQuery's each().
+   * $('div.calendar').once().each(function() {
+   *   // Since there is no once ID provided here, the key will be "once".
+   * });
+   * ```
    *
    * @see removeOnce
    * @see findOnce
@@ -69,33 +87,39 @@
    * @public
    */
   $.fn.once = function (id) {
-    // Build the name for the data identifier. Generate a new unique id if the
-    // id parameter is not provided.
+    // Build the name for the data identifier. Generate a new unique ID if the
+    // ID parameter is not provided.
     var name = "jquery-once-" + checkId(id);
 
-    // Filter the elements by which do not have the data yet.
+    // Filter the elements by whi*ch do not have the data yet.
     return this.filter(function() {
       return $(this).data(name) !== true;
     }).data(name, true);
   };
 
   /**
-   * Removes the once data from the given elements, based on the given ID.
+   * Removes the once data from elements, based on the given ID.
    *
-   * @param {string} [id]
-   *   A string representing the name of the data id which should be used when
+   * @param {string} [id="once"]
+   *   A string representing the name of the data ID which should be used when
    *   filtering the elements. This only filters elements that have already been
-   *   processed by the once function. The id should be the same id that was
-   *   originally passed to the once() function. Defaults to "once".
+   *   processed by the once function. The ID should be the same ID that was
+   *   originally passed to the once() function. Defaults to `"once"`.
    *
-   * @returns jQuery element collection of elements that now have their once
-   *   data removed.
+   * @returns jQuery collection of elements that were acted upon to remove their
+   *    once data.
    *
    * @example
-   * // Remove once data with the "changecolor" ID.
-   * $('p').removeOnce('changecolor').each(function() {
-   *   // This function is called for all elements that had their once removed.
+   * ``` javascript
+   * // Remove once data with the "changecolor" ID. The result set is the
+   * // elements that had their once data removed.
+   * $('p').removeOnce("changecolor").css("color", "");
+   *
+   * // Any jQuery function can be performed on the result set.
+   * $("div.calendar").removeOnce().each(function() {
+   *   // Remove the calendar behavior.
    * });
+   * ```
    *
    * @see once
    * @this jQuery
@@ -111,20 +135,28 @@
   /**
    * Filters elements that have already been processed once.
    *
-   * @param {string} [id]
+   * @param {string} [id="once"]
    *   A string representing the name of the data id which should be used when
    *   filtering the elements. This only filters elements that have already
    *   been processed by the once function. The id should be the same id that
    *   was originally passed to the once() function. Defaults to "once".
    *
-   * @returns jQuery element collection of elements that have been run once.
+   * @returns jQuery collection of elements that have been run once.
    *
    * @example
-   * // Find all elements that have the changecolor'ed once.
+   * ``` javascript
+   * // Find all elements that have been changecolor'ed once.
    * $('p').findOnce('changecolor').each(function() {
    *   // This function is called for all elements that has already once'd.
    * });
    *
+   * // Find all elements that have been acted on with the default "once" key.
+   * $('p').findOnce().each(function() {
+   *   // This function is called for all elements that have been acted on with
+   *   // a "once" action.
+   * });
+   * ```
+   *
    * @see once
    * @this jQuery
    *