From 9db804b413a36b678ca867003c0b85222f70b186 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 9 Sep 2014 10:51:46 -0700
Subject: [PATCH] Doc events in `Cursor`

---
 src/cursor.coffee | 50 +++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 26 deletions(-)

diff --git a/src/cursor.coffee b/src/cursor.coffee
index a35cf4d68..ce7061fef 100644
--- a/src/cursor.coffee
+++ b/src/cursor.coffee
@@ -9,31 +9,6 @@ Grim = require 'grim'
 #
 # Cursors belong to {Editor}s and have some metadata attached in the form
 # of a {Marker}.
-#
-# ## Events
-#
-# ### moved
-#
-# Extended: Emit when a cursor has been moved. If there are multiple cursors,
-# it will be emit for each cursor.
-#
-# * `event` {Object}
-#   * `oldBufferPosition` {Point}
-#   * `oldScreenPosition` {Point}
-#   * `newBufferPosition` {Point}
-#   * `newScreenPosition` {Point}
-#   * `textChanged` {Boolean}
-#
-# ### destroyed
-#
-# Extended: Emit when the cursor is destroyed
-#
-# ### visibility-changed
-#
-# Extended: Emit when the Cursor is hidden or shown
-#
-# * `visible` {Boolean} true when cursor is visible
-#
 module.exports =
 class Cursor extends Model
   screenPosition: null
@@ -79,19 +54,41 @@ class Cursor extends Model
       @emitter.dispose()
     @needsAutoscroll = true
 
+  # Essential: Calls your `callback` when the cursor has been moved.
+  #
+  # * `callback` {Function}
+  #   * `event` {Object}
+  #     * `oldBufferPosition` {Point}
+  #     * `oldScreenPosition` {Point}
+  #     * `newBufferPosition` {Point}
+  #     * `newScreenPosition` {Point}
+  #     * `textChanged` {Boolean}
   onDidChangePosition: (callback) ->
     @emitter.on 'did-change-position', callback
 
+  # Extended: Calls your `callback` when the cursor is destroyed
+  #
+  # * `callback` {Function}
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 
+  # Extended: Calls your `callback` when the cursor's visibility has changed
+  #
+  # * `callback` {Function}
+  #   * `visibility` {Boolean}
+  onDidChangeVisibility: (callback) ->
+    @emitter.on 'did-change-visibility', callback
+
   on: (eventName) ->
     switch eventName
       when 'moved'
         Grim.deprecate("Use Cursor::onDidChangePosition instead")
       when 'destroyed'
         Grim.deprecate("Use Cursor::onDidDestroy instead")
-
+      when 'destroyed'
+        Grim.deprecate("Use Cursor::onDidDestroy instead")
+      else
+        Grim.deprecate("::on is no longer supported. Use the event subscription methods instead")
     super
 
   destroy: ->
@@ -153,6 +150,7 @@ class Cursor extends Model
       @visible = visible
       @needsAutoscroll ?= true if @visible and @isLastCursor()
       @emit 'visibility-changed', @visible
+      @emitter.emit 'did-change-visibility', @visible
 
   # Public: Returns the visibility of the cursor.
   isVisible: -> @visible