Remove function callback

4 files changed, 27 insertions, 74 deletions

diff --git a/HISTORY.md b/HISTORY.md
index 767ef10..a6809ed 100644
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -1,5 +1,8 @@
 # History
 
+## v2.0.0-alpha.6 October 5, 2014
+- Removed function callback in order to promote jQuery chaining standards
+
 ## v2.0.0-alpha.5 October 5, 2014
 - Added findOnce() to allow filtering once'd elements
 - Added inline JavaScript code documentation
diff --git a/example/index.html b/example/index.html
index 0c2505f..4b73760 100644
--- a/example/index.html
+++ b/example/index.html
@@ -9,14 +9,10 @@
         <p>This is some text, which should stay green.</p>
         <script>
           // Change the color of the text to green.
-          $('p').once('changecolor', function() {
-            $(this).css('color', 'green');
-          });
+          $('p').once('changecolor').css('color', 'green');
 
           // Attempt to change the color again.
-          $('p').once('changecolor', function() {
-            $(this).css('color', 'red');
-          });
+          $('p').once('changecolor').css('color', 'red');
         </script>
     </body>
 </html>
diff --git a/jquery.once.js b/jquery.once.js
index dfde181..222aef4 100644
--- a/jquery.once.js
+++ b/jquery.once.js
@@ -1,7 +1,7 @@
 /*!
  * @file jQuery Once
  * @description Act on jQuery elements only once.
- * @version 2.0.0-alpha.5
+ * @version 2.0.0-alpha.6
  * @link http://github.com/robloach/jquery-once
  * @author Rob Loach (http://robloach.net)
  * @license MIT, GPL-2.0
@@ -23,32 +23,18 @@
   /**
    * Filters elements by whether they have not yet been processed.
    *
-   * @param {(string|function)} [id]
+   * @param {string} [id]
    *   (Optional) If this is a string, then it will be the data ID used
    *   to determine whether it has already been processed or not.
    *
-   *   If the id parameter is a function, it will be passed off to the fn
-   *   parameter and the id will become a unique identifier, represented as a
-   *   number.
-   *
-   *   When the id is neither a string or a function, it becomes a unique
-   *   identifier, depicted as a number. The element's data ID will then be
-   *   represented in the form of "jquery-once-#".
-   * @param {function} [fn]
-   *   (Optional) If given, this function will be called for each element that
-   *   has not yet been processed. The function's return value follows the same
-   *   logic as $.each(). Returning true will continue to the next matched
-   *   element in the set, while returning false will entirely break the
-   *   iteration.
+   *   When the id is not passed, it becomes a unique identifier, depicted as a
+   *   number. The element's data ID will then be represented in the form of
+   *   "jquery-once-#".
    * @returns jQuery element collection of elements that have now run once.
    *
    * @example
    * // Change the color to green only once.
-   * $('p').once('changecolor', function() {
-   *   // This function is called for every p element that hasn't been called
-   *   // with "changecolor" once() before.
-   *   $(this).css('color', 'green');
-   * });
+   * $('p').once('changecolor').css('color', 'green');
    *
    * @see removeOnce
    * @see findOnce
@@ -56,26 +42,21 @@
    * @public
    * @global
    */
-  $.fn.once = function (id, fn) {
+  $.fn.once = function (id) {
     if (typeof id !== 'string') {
-      // Generate a numeric ID if the id passed can't be used as a CSS class.
+      // Generate a numeric ID if the id passed is not a string.
       if (!(id in cache)) {
         cache[id] = ++uuid;
       }
-      // When the fn parameter is not passed, we interpret it from the id.
-      if (!fn) {
-        fn = id;
-      }
       id = cache[id];
     }
 
     // Filter the elements by which do not have the data yet.
     var name = 'jquery-once-' + id;
-    var elements = this.filter(function() {
+
+    return this.filter(function() {
       return $(this).data(name) !== true;
     }).data(name, true);
-
-    return $.isFunction(fn) ? elements.each(fn) : elements;
   };
 
   /**
@@ -86,19 +67,13 @@
    *   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.
-   * @param {function} [fn]
-   *   (Optional) If given, this function will be called for each element that
-   *   whose element's once data was removed. The function's return value
-   *   follows the same logic as $.each(). Returning true will continue to the
-   *   next matched element in the set, while returning false will entirely
-   *   break the iteration.
    *
    * @returns jQuery element collection of elements that now have their once
    *   data removed.
    *
    * @example
    * // Remove once data with the "changecolor" ID.
-   * $('p').removeOnce('changecolor', function() {
+   * $('p').removeOnce('changecolor').each(function() {
    *   // This function is called for all elements that had their once removed.
    * });
    *
@@ -107,14 +82,9 @@
    * @public
    * @global
    */
-  $.fn.removeOnce = function (id, fn) {
+  $.fn.removeOnce = function (id) {
     // Filter through the elements to find the once'd elements.
-    var elements = this.findOnce(id);
-
-    // Remove the once data from the elements.
-    elements.removeData('jquery-once-' + id);
-
-    return $.isFunction(fn) ? elements.each(fn) : elements;
+    return this.findOnce(id).removeData('jquery-once-' + id);
   };
 
   /**
@@ -125,18 +95,12 @@
    *   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.
-   * @param {function} [fn]
-   *   (Optional) If given, this function will be called for each element that
-   *   has not yet been processed. The function's return value follows the same
-   *   logic as $.each(). Returning true will continue to the next matched
-   *   element in the set, while returning false will entirely break the
-   *   iteration.
    *
    * @returns jQuery element collection of elements that have been run once.
    *
    * @example
    * // Find all elements that have the changecolor'ed once.
-   * $('p').findOnce('changecolor', function() {
+   * $('p').findOnce('changecolor').each(function() {
    *   // This function is called for all elements that has already once'd.
    * });
    *
@@ -145,13 +109,11 @@
    * @public
    * @global
    */
-  $.fn.findOnce = function (id, fn) {
+  $.fn.findOnce = function (id) {
     // Filter the elements by which do have the data.
     var name = 'jquery-once-' + id;
-    var elements = this.filter(function() {
+    return this.filter(function() {
       return $(this).data(name) === true;
     });
-
-    return $.isFunction(fn) ? elements.each(fn) : elements;
   };
 }));
diff --git a/test/test.js b/test/test.js
index 6e6353f..88d59e7 100644
--- a/test/test.js
+++ b/test/test.js
@@ -1,8 +1,6 @@
 test("Properly executed", function() {
   // Create one once() call.
-  $('#test1 span').once(function() {
-    $(this).data('test1', 'foobar');
-  });
+  $('#test1 span').once().data('test1', 'foobar');
 
   var data = $('#test1 span').data('test1');
   ok(data === "foobar");
@@ -21,7 +19,7 @@ test("Called only once", function() {
 
   // Call once() a bunch of times.
   for (var i = 0; i < 10; i++) {
-    $('#test2 span').once('count', callback);
+    $('#test2 span').once('count').each(callback);
   }
 
   // Verify that it was only called once.
@@ -35,9 +33,7 @@ test("Apply the value to data correctly", function() {
   ok(!hasData, 'Value not applied in the beginning.');
 
   // Create one once() call.
-  $('#test3 span').once('test3', function() {
-    // Do nothing.
-  });
+  $('#test3 span').once('test3');
 
   // Verify the data is applied.
   hasData = $('#test3 span').data('jquery-once-test3');
@@ -46,9 +42,7 @@ test("Apply the value to data correctly", function() {
 
 test("Remove the value from attribute correctly", function() {
   // Create one once() call.
-  $('#test4 span').once('test4', function() {
-    // Do nothing.
-  });
+  $('#test4 span').once('test4');
 
   // Verify the data is applied.
   var hasData = $('#test4 span').data('jquery-once-test4');
@@ -62,12 +56,10 @@ test("Remove the value from attribute correctly", function() {
 
 test("Finding elements correctly through findOnce()", function() {
   // Create one once() call.
-  $('#test5 span').once('test5', function() {
-    // Do nothing.
-  });
+  $('#test5 span').once('test5');
 
   // Find the once'd element through the callback.
-  var elements = $('span').findOnce('test5', function() {
+  var elements = $('span').findOnce('test5').each(function() {
     var hasData = $(this).data('jquery-once-test5');
     ok(hasData, 'Finding the correct span element after once() through callback.');
   });