1 files changed, 60 insertions, 28 deletions
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
    *