Return emitter in #on(), #off(), #once(), so calls can be chained.

src/core/Emitter.js

@@ -36,6 +36,7 @@ var Emitter = {
                     entry.install.call(this, type);
             }
         }
+        return this;
     },
 
     off: function(type, func) {
@@ -62,10 +63,11 @@ var Emitter = {
                 handlers.splice(index, 1);
             }
         }
+        return this;
     },
 
     once: function(type, func) {
-        this.on(type, function() {
+        return this.on(type, function() {
             func.apply(this, arguments);
             this.off(type, func);
         });

src/item/Item.js

@@ -3555,6 +3555,7 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * type
      * @param {Function} function The function to be called when the event
      * occurs
+     * @return {Item} this item itself, so calls can be chained
      *
      * @example {@paperscript}
      * // Change the fill color of the path to red when the mouse enters its
@@ -3584,7 +3585,8 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * @function
      * @param {Object} object an object literal containing one or more of the
      * following properties: {@code mousedown, mouseup, mousedrag, click,
-     * doubleclick, mousemove, mouseenter, mouseleave}.
+     * doubleclick, mousemove, mouseenter, mouseleave}
+     * @return {Item} this item itself, so calls can be chained
      *
      * @example {@paperscript}
      * // Change the fill color of the path to red when the mouse enters its
@@ -3643,6 +3645,7 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event
      * type
      * @param {Function} function The function to be detached
+     * @return {Item} this item itself, so calls can be chained
      */
     /**
      * Detach one or more event handlers to the item.
@@ -3652,6 +3655,7 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * @param {Object} object an object literal containing one or more of the
      * following properties: {@code mousedown, mouseup, mousedrag, click,
      * doubleclick, mousemove, mouseenter, mouseleave}
+     * @return {Item} this item itself, so calls can be chained
      */
 
     /**
@@ -3663,7 +3667,8 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * 'doubleclick', 'mousemove', 'mouseenter', 'mouseleave')} type the event
      * type
      * @param {Object} event an object literal containing properties describing
-     * the event.
+     * the event
+     * @return {Boolean} {@true if the event had listeners}
      */
 
     /**

src/tool/Tool.js

@@ -417,6 +417,7 @@ var Tool = PaperScopeItem.extend(/** @lends Tool# */{
      * 'keydown', 'keyup')} type the event type
      * @param {Function} function The function to be called when the event
      * occurs
+     * @return {Tool} this tool itself, so calls can be chained
      */
     /**
      * Attach one or more event handlers to the tool.
@@ -425,7 +426,8 @@ var Tool = PaperScopeItem.extend(/** @lends Tool# */{
      * @function
      * @param {Object} param an object literal containing one or more of the
      * following properties: {@code mousedown, mouseup, mousedrag, mousemove,
-     * keydown, keyup}.
+     * keydown, keyup}
+     * @return {Tool} this tool itself, so calls can be chained
      */
 
     /**
@@ -436,6 +438,7 @@ var Tool = PaperScopeItem.extend(/** @lends Tool# */{
      * @param {String('mousedown', 'mouseup', 'mousedrag', 'mousemove',
      * 'keydown', 'keyup')} type the event type
      * @param {Function} function The function to be detached
+     * @return {Tool} this tool itself, so calls can be chained
      */
     /**
      * Detach one or more event handlers from the tool.
@@ -445,6 +448,7 @@ var Tool = PaperScopeItem.extend(/** @lends Tool# */{
      * @param {Object} param an object literal containing one or more of the
      * following properties: {@code mousedown, mouseup, mousedrag, mousemove,
      * keydown, keyup}
+     * @return {Tool} this tool itself, so calls can be chained
      */
 
     /**
@@ -455,7 +459,8 @@ var Tool = PaperScopeItem.extend(/** @lends Tool# */{
      * @param {String('mousedown', 'mouseup', 'mousedrag', 'mousemove',
      * 'keydown', 'keyup')} type the event type
      * @param {Object} event an object literal containing properties describing
-     * the event.
+     * the event
+     * @return {Boolean} {@true if the event had listeners}
      */
 
     /**

src/view/View.js

@@ -489,7 +489,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
 
     // DOCS: projectToView(point), viewToProject(point)
     /**
-     * @param {Point}
+     * @param {Point} point
      * @return {Point}
      */
     projectToView: function(/* point */) {
@@ -497,7 +497,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
     },
 
     /**
-     * @param {Point}
+     * @param {Point} point
      * @return {Point}
      */
     viewToProject: function(/* point */) {
@@ -564,6 +564,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
      * @param {String('frame', 'resize')} type the event type
      * @param {Function} function The function to be called when the event
      * occurs
+     * @return {View} this view itself, so calls can be chained
      *
      * @example {@paperscript}
      * // Create a rectangle shaped path with its top left point at:
@@ -585,6 +586,9 @@ var View = Base.extend(Emitter, /** @lends View# */{
      * @function
      * @param {Object} param an object literal containing one or more of the
      * following properties: {@code frame, resize}.
+     * @return {View} this view itself, so calls can be chained
+     *
+     * @example {@paperscript}
      * // Create a rectangle shaped path with its top left point at:
      * // {x: 50, y: 25} and a size of {width: 50, height: 50}
      * var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50));
@@ -607,6 +611,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
      * @function
      * @param {String('frame', 'resize')} type the event type
      * @param {Function} function The function to be detached
+     * @return {View} this view itself, so calls can be chained
      *
      * @example {@paperscript}
      * // Create a rectangle shaped path with its top left point at:
@@ -636,6 +641,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
      * @function
      * @param {Object} param an object literal containing one or more of the
      * following properties: {@code frame, resize}
+     * @return {View} this view itself, so calls can be chained
      */
 
     /**
@@ -646,6 +652,7 @@ var View = Base.extend(Emitter, /** @lends View# */{
      * @param {String('frame', 'resize')} type the event type
      * @param {Object} event an object literal containing properties describing
      * the event.
+     * @return {Boolean} {@true if the event had listeners}
      */
 
     /**