Add Returns line to all the event subscription methods

src/cursor.coffee

@@ -67,12 +67,16 @@ class Cursor extends Model
   #     * `newBufferPosition` {Point}
   #     * `newScreenPosition` {Point}
   #     * `textChanged` {Boolean}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangePosition: (callback) ->
     @emitter.on 'did-change-position', callback
 
   # Extended: Calls your `callback` when the cursor is destroyed
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 
@@ -80,6 +84,8 @@ class Cursor extends Model
   #
   # * `callback` {Function}
   #   * `visibility` {Boolean}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeVisibility: (callback) ->
     @emitter.on 'did-change-visibility', callback
 

src/decoration.coffee

@@ -65,12 +65,16 @@ class Decoration
   #   * `event` {Object}
   #     * `oldProperties` {Object} the old parameters the decoration used to have
   #     * `newProperties` {Object} the new parameters the decoration now has
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeProperties: (callback) ->
     @emitter.on 'did-change-properties', callback
 
   # Essential: Invoke the given callback when the {Decoration} is destroyed
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 

src/editor.coffee

@@ -179,18 +179,24 @@ class Editor extends Model
   # Essential: Calls your `callback` when the buffer's title has changed.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeTitle: (callback) ->
     @emitter.on 'did-change-title', callback
 
   # Essential: Calls your `callback` when the buffer's path, and therefore title, has changed.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangePath: (callback) ->
     @emitter.on 'did-change-path', callback
 
   # Extended: Calls your `callback` when soft wrap was enabled or disabled.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeSoftWrapped: (callback) ->
     @displayBuffer.onDidChangeSoftWrapped(callback)
 
@@ -198,6 +204,8 @@ class Editor extends Model
   # been changed.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeGrammar: (callback) ->
     @emitter.on 'did-change-grammar', callback
 
@@ -206,12 +214,16 @@ class Editor extends Model
   # to handle changes to the buffer without compromising typing performance.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidStopChanging: (callback) ->
     @getBuffer().onDidStopChanging(callback)
 
   # Extended: Calls your `callback` when the result of {::isModified} changes.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeModified: (callback) ->
     @getBuffer().onDidChangeModified(callback)
 
@@ -219,6 +231,8 @@ class Editor extends Model
   # disk at a moment when the result of {::isModified} is true.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidConflict: (callback) ->
     @getBuffer().onDidConflict(callback)
 
@@ -228,6 +242,8 @@ class Editor extends Model
   #   * `event` event {Object}
   #     * `text` {String} text to be inserted
   #     * `cancel` {Function} Call to prevent the text from being inserted
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onWillInsertText: (callback) ->
     @emitter.on 'will-insert-text', callback
 
@@ -236,6 +252,8 @@ class Editor extends Model
   # * `callback` {Function}
   #   * `event` event {Object}
   #     * `text` {String} text to be inserted
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidInsertText: (callback) ->
     @emitter.on 'did-insert-text', callback
 
@@ -244,6 +262,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `selection` {Selection} that was added
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   observeCursors: (callback) ->
     callback(cursor) for cursor in @getCursors()
     @onDidAddCursor(callback)
@@ -252,6 +272,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `cursor` {Cursor} that was added
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidAddCursor: (callback) ->
     @emitter.on 'did-add-cursor', callback
 
@@ -259,6 +281,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `cursor` {Cursor} that was removed
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidRemoveCursor: (callback) ->
     @emitter.on 'did-remove-cursor', callback
 
@@ -272,6 +296,8 @@ class Editor extends Model
   #     * `newBufferPosition` {Point}
   #     * `newScreenPosition` {Point}
   #     * `textChanged` {Boolean}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeCursorPosition: (callback) ->
     @emitter.on 'did-change-cursor-position', callback
 
@@ -280,6 +306,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `selection` {Selection} that was added
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   observeSelections: (callback) ->
     callback(selection) for selection in @getSelections()
     @onDidAddSelection(callback)
@@ -288,6 +316,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `selection` {Selection} that was added
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidAddSelection: (callback) ->
     @emitter.on 'did-add-selection', callback
 
@@ -295,6 +325,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `selection` {Selection} that was removed
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidRemoveSelection: (callback) ->
     @emitter.on 'did-remove-selection', callback
 
@@ -302,6 +334,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `selection` {Selection} that moved
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeSelectionRange: (callback) ->
     @emitter.on 'did-change-selection-range', callback
 
@@ -310,6 +344,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `decoration` {Decoration}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   observeDecorations: (callback) ->
     @displayBuffer.observeDecorations(callback)
 
@@ -317,6 +353,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `decoration` {Decoration} that was added
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidAddDecoration: (callback) ->
     @displayBuffer.onDidAddDecoration(callback)
 
@@ -324,6 +362,8 @@ class Editor extends Model
   #
   # * `callback` {Function}
   #   * `decoration` {Decoration} that was removed
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidRemoveDecoration: (callback) ->
     @displayBuffer.onDidRemoveDecoration(callback)
 

src/git.coffee

@@ -113,6 +113,8 @@ class Git
   #     * `path` {String} the old parameters the decoration used to have
   #     * `pathStatus` {Number} representing the status. This value can be passed to
   #       {::isStatusModified} or {::isStatusNew} to get more information.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeStatus: (callback) ->
     @emitter.on 'did-change-status', callback
 
@@ -122,6 +124,8 @@ class Git
   # {::getPathStatus(path)} to get the status for your path of choice.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeStatuses: (callback) ->
     @emitter.on 'did-change-statuses', callback
 

src/package-manager.coffee

@@ -51,12 +51,16 @@ class PackageManager
   # Essential: Invoke the given callback when all packages have been activated.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidLoadAll: (callback) ->
     @emitter.on 'did-load-all', callback
 
   # Essential: Invoke the given callback when all packages have been activated.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidActivateAll: (callback) ->
     @emitter.on 'did-activate-all', callback
 

src/package.coffee

@@ -56,6 +56,8 @@ class Package
   # Essential: Invoke the given callback when all packages have been activated.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDeactivate: (callback) ->
     @emitter.on 'did-deactivate', callback
 

src/selection.coffee

@@ -38,12 +38,16 @@ class Selection extends Model
   #
   # * `callback` {Function}
   #   * `screenRange` {Range} indicating the new screenrange
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeRange: (callback) ->
     @emitter.on 'did-change-range', callback
 
   # Extended: Calls your `callback` when the selection was destroyed
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 

src/theme-manager.coffee

@@ -36,6 +36,8 @@ class ThemeManager
   #
   # * `callback` {Function}
   #   * `stylesheet` {StyleSheet} the style node
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidAddStylesheet: (callback) ->
     @emitter.on 'did-add-stylesheet', callback
 
@@ -43,12 +45,16 @@ class ThemeManager
   #
   # * `callback` {Function}
   #   * `stylesheet` {StyleSheet} the style node
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidRemoveStylesheet: (callback) ->
     @emitter.on 'did-remove-stylesheet', callback
 
   # Essential: Invoke `callback` when any stylesheet has been updated, added, or removed.
   #
   # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeStylesheets: (callback) ->
     @emitter.on 'did-change-stylesheets', callback