Update JSDoc and cleaned up code for #17

lib/backbone-pageable.js

@@ -324,8 +324,7 @@
     },
 
     /**
-       Makes a Backbone.Collection that contains all the pages and connect event
-       handlers to it.
+       Makes a Backbone.Collection that contains all the pages.
 
        @private
        @param {Array.<Object|Backbone.Model>} models
@@ -348,10 +347,9 @@
 
       var fullCollection = new (Backbone.Collection.extend(proto))(models, options);
 
-      var self = this;
       for (i = 0, length = properties.length; i < length; i++) {
         prop = properties[i];
-        if (self[prop] !== thisProto[prop]) {
+        if (this[prop] !== thisProto[prop]) {
           fullCollection[prop] = prop;
         }
       }
@@ -371,7 +369,7 @@
 
        @return {function(string, Backbone.Model, Backbone.Collection, Object)}
        Collection event handler
-     */
+    */
     _makeCollectionEventHandler: function (pageCol, fullCol) {
 
       return function collectionEventHandler (event, model, collection, options) {
@@ -404,7 +402,8 @@
           else {
             fullIndex = pageStart + pageCol.indexOf(model);
             colToAdd = fullCol;
-            addAt = fullIndex;
+            var at = options && options.at || fullIndex;
+            addAt = (at < pageStart || at >= pageEnd) ? at : fullIndex;
           }
 
           if (colToAdd) {
@@ -641,7 +640,7 @@
 
     /**
        Fetch the first page in server mode, or reset the current page of this
-       collection to the first page in client mode.
+       collection to the first page in client or infinite mode.
 
        @param {Object} options {@link #getPage} options.
 
@@ -655,7 +654,7 @@
 
     /**
        Fetch the previous page in server mode, or reset the current page of this
-       collection to the previous page in client mode.
+       collection to the previous page in client or infinite mode.
 
        @param {Object} options {@link #getPage} options.
 
@@ -699,10 +698,13 @@
        Given a page index, set #state.currentPage to that index. If this
        collection is in server mode, fetch the page using the updated state,
        otherwise, reset the current page of this collection to the page
-       specified by `pageIndex` in client mode. If `options.fetch` is true, a
-       fetch can be forced in client mode before resetting the current
-       page. Under infinite mode, the index is the page name for looking up a
-       URL from #links.
+       specified by `index` in client mode. If `options.fetch` is true, a fetch
+       can be forced in client mode before resetting the current page. Under
+       infinite mode, if the index is less than the current page, a reset is
+       done as in client mode. If the index is greater than the current page
+       number, a fetch is made from #fullCollection using the same URL and the
+       results are appended to #fullCollection instead of replaced. The current
+       page will then be reset after fetching.
 
        @param {number|string} index The page index to go to, or the page name to
        look up from #links in infinite mode.
@@ -764,9 +766,18 @@
         var url = links.current = links[pageNum] = links[index];
         if (options.fetch) options.url = url;
 
-        return this.fetch(
-          _.extend({url: url, add: true, update: true, remove: false},
-                   _.omit(options, "fetch")));
+        var fullCollection = this.fullCollection;
+        var self = this;
+        return this.fetch(_.extend({url: url,
+                                    add: true,
+                                    update: true,
+                                    remove: false,
+                                    at: fullCollection.length},
+                                   _.omit(options, "fetch"))).
+          done(function (resp, status, xhr) {
+            _.extend(self.links, self.parseLinks(resp, {xhr: xhr}));
+            return self.reset(fullCollection.models.slice(pageStart, pageEnd));
+          });
       }
 
       return this.fetch(_.omit(options, "fetch"));
@@ -871,9 +882,12 @@
 
     /**
        Fetch a page from the server in server mode, or all the pages in client
-       mode. The query string is constructed by translating the current
-       pagination state to your server API query parameter using #queryParams.
-       The current page will reset after fetch.
+       mode. Under infinite mode, the current page is refetched by default and
+       then reset.
+
+       The query string is constructed by translating the current pagination
+       state to your server API query parameter using #queryParams.  The current
+       page will reset after fetch.
 
        @param {Object} [options] Accepts all
        [Backbone.Collection#fetch](http://backbonejs.org/#Collection-fetch)
@@ -889,7 +903,9 @@
 
       var mode = this.mode;
 
-      if (mode == "infinite" && !options.url) options.url = this.links.current;
+      if (mode == "infinite" && !options.url) {
+        return this.getPage(this.state.currentPage, {fetch: true});
+      }
 
       var state = this._checkState(this.state);
 
@@ -939,23 +955,7 @@
         return BBColProto.fetch.call(this, _.extend({}, options, {silent: true}));
       }
 
-      if (mode != "infinite") {
-        return BBColProto.fetch.call(this, options);
-      }
-      else {
-        var oldParse = fullCollection.parse;
-        fullCollection.parse = _.bind(this.parse, this);
-        var self = this;
-        return fullCollection.fetch(options).done(function (resp, status, xhr) {
-          _.extend(self.links, self.parseLinks(resp, {xhr: xhr}));
-          var currentPage = state.currentPage;
-          var pageStart = (state.firstPage === 0 ? currentPage : currentPage - 1) * state.pageSize;
-          var pageEnd = pageStart + state.pageSize;
-          return self.reset(fullCollection.models.slice(pageStart, pageEnd));
-        }).always(function () {
-          fullCollection.parse = oldParse;
-        });
-      }
+      return BBColProto.fetch.call(this, options);
     },
 
     /**