Make transform interfaces more consistent

transform() and transformPosition() now both return the argument
tranformed

README.md

@@ -315,7 +315,7 @@ a.compose(b);  // a == new Delta().insert('ac');
 
 ### transform()
 
-Transform against another Delta. This method is self modifying.
+Transform given Delta against own operations.
 
 #### Methods
 
@@ -327,13 +327,17 @@ Transform against another Delta. This method is self modifying.
 - `other` - Delta to transform
 - `priority` - Boolean used to break ties
 
+#### Returns
+
+- `Delta` - transformed Delta
+
 #### Example
 
 ```js
 var a = new Delta().insert('a');
 var b = new Delta().insert('b');
 
-a.transform(b, true);  // a == new Delta().retain(1).insert('b');
+b = a.transform(b, true);  // new Delta().retain(1).insert('b');
 ```
 
 ---
@@ -350,6 +354,10 @@ Transform an index against the delta. Useful for representing cursor/selection p
 
 - `index` - index to transform
 
+#### Returns
+
+- `Number` - transformed index
+
 #### Example
 
 ```js
@@ -376,6 +384,10 @@ Calculates the difference between two documents expressed as a Delta.
 
 - `other` - Document Delta to diff against
 
+#### Returns
+
+- `Delta` - difference between the two documents
+
 #### Example
 
 ```js

lib/delta.js

@@ -190,12 +190,12 @@ Delta.prototype.transform = function (other, priority) {
   }
   var thisIter = op.iterator(this.ops);
   var otherIter = op.iterator(other.ops);
-  this.ops = [];
+  var delta = new Delta();
   while (thisIter.hasNext() || otherIter.hasNext()) {
     if (thisIter.peekType() === 'insert' && (priority || otherIter.peekType() !== 'insert')) {
-      this.retain(op.length(thisIter.next()));
+      delta.retain(op.length(thisIter.next()));
     } else if (otherIter.peekType() === 'insert') {
-      this.push(otherIter.next());
+      delta.push(otherIter.next());
     } else {
       var length = Math.min(thisIter.peekLength(), otherIter.peekLength());
       var thisOp = thisIter.next(length);
@@ -204,14 +204,14 @@ Delta.prototype.transform = function (other, priority) {
         // Our delete either makes their delete redundant or removes their retain
         continue;
       } else if (otherOp['delete']) {
-        this.push(otherOp);
+        delta.push(otherOp);
       } else {
         // We retain either their retain or insert
-        this.retain(length, op.attributes.transform(thisOp.attributes, otherOp.attributes, priority));
+        delta.retain(length, op.attributes.transform(thisOp.attributes, otherOp.attributes, priority));
       }
     }
   }
-  return this.chop();
+  return delta.chop();
 };
 
 Delta.prototype.transformPosition = function (index, priority) {