Update documentation for new MarkerLayer.onDidUpdate behavior

Author: as-cii

spec/display-marker-layer-spec.coffee

@@ -140,26 +140,26 @@ describe "DisplayMarkerLayer", ->
     markerLayer.onDidUpdate (event) -> events.push({
       created: Array.from(event.created),
       updated: Array.from(event.updated),
-      invalidated: Array.from(event.invalidated),
+      touched: Array.from(event.touched),
       destroyed: Array.from(event.destroyed)
     })
 
     events = []
     marker = markerLayer.markScreenRange([[0, 4], [1, 4]], {invalidate: 'inside'})
     expect(events).toEqual([
-      {created: [marker.id], updated: [], invalidated: [], destroyed: []}
+      {created: [marker.id], updated: [], touched: [], destroyed: []}
     ])
 
     events = []
     marker.setScreenRange([[0, 5], [1, 0]])
     expect(events).toEqual([
-      {created: [], updated: [marker.id], invalidated: [], destroyed: []}
+      {created: [], updated: [marker.id], touched: [], destroyed: []}
     ])
 
     events = []
     buffer.insert([0, 8], 'foo')
     expect(events).toEqual([
-      {created: [], updated: [], invalidated: [marker.id], destroyed: []}
+      {created: [], updated: [], touched: [marker.id], destroyed: []}
     ])
 
     events = []
@@ -168,10 +168,9 @@ describe "DisplayMarkerLayer", ->
 
     events = []
     marker.destroy()
-    expect(events.length).toBe(1)
-    expect(Array.from(events[0].created)).toEqual []
-    expect(Array.from(events[0].updated)).toEqual []
-    expect(Array.from(events[0].destroyed)).toEqual [marker.id]
+    expect(events).toEqual([
+      {created: [], updated: [], touched: [], destroyed: [marker.id]}
+    ])
 
   it "allows markers to be copied", ->
     buffer = new TextBuffer(text: '\ta\tbc\tdef\tg\n\th')

spec/marker-layer-spec.coffee

@@ -183,7 +183,7 @@ describe "MarkerLayer", ->
       layer.onDidUpdate (event) -> events.push({
         created: Array.from(event.created),
         updated: Array.from(event.updated),
-        invalidated: Array.from(event.invalidated),
+        touched: Array.from(event.touched),
         destroyed: Array.from(event.destroyed)
       })
 
@@ -195,8 +195,8 @@ describe "MarkerLayer", ->
       marker3 = layer.markRange([[4, 0], [4, 5]])
 
       expect(events).toEqual([
-        {created: [marker1.id, marker2.id], updated: [], invalidated: [], destroyed: []},
-        {created: [marker3.id], updated: [], invalidated: [], destroyed: []}
+        {created: [marker1.id, marker2.id], updated: [], touched: [], destroyed: []},
+        {created: [marker3.id], updated: [], touched: [], destroyed: []}
       ])
 
       events = []
@@ -206,7 +206,7 @@ describe "MarkerLayer", ->
         marker3.destroy()
 
       expect(events).toEqual([
-        {created: [], updated: [marker1.id, marker2.id], invalidated: [], destroyed: [marker3.id]}
+        {created: [], updated: [marker1.id, marker2.id], touched: [], destroyed: [marker3.id]}
       ])
 
       events = []
@@ -216,17 +216,17 @@ describe "MarkerLayer", ->
       buffer.insert([1, 5], 'zzz')
 
       expect(events).toEqual([
-        {created: [], updated: [], invalidated: [marker1.id], destroyed: []},
-        {created: [], updated: [], invalidated: [marker1.id], destroyed: []}
+        {created: [], updated: [], touched: [marker1.id], destroyed: []},
+        {created: [], updated: [], touched: [marker1.id], destroyed: []}
       ])
 
       events = []
       buffer.undo()
       buffer.undo()
 
       expect(events).toEqual([
-        {created: [], updated: [], invalidated: [marker1.id], destroyed: []},
-        {created: [], updated: [], invalidated: [marker1.id], destroyed: []}
+        {created: [], updated: [], touched: [marker1.id], destroyed: []},
+        {created: [], updated: [], touched: [marker1.id], destroyed: []}
       ])
 
       events = []
@@ -240,8 +240,8 @@ describe "MarkerLayer", ->
         buffer.insert([4, 3], 'fff')
 
       expect(events).toEqual([
-        {created: [], updated: [], invalidated: [marker1.id, marker2.id], destroyed: []},
-        {created: [], updated: [], invalidated: [marker2.id], destroyed: []}
+        {created: [], updated: [], touched: [marker1.id, marker2.id], destroyed: []},
+        {created: [], updated: [], touched: [marker2.id], destroyed: []}
       ])
 
       events = []
@@ -252,8 +252,8 @@ describe "MarkerLayer", ->
         marker2.clearTail()
 
       expect(events).toEqual([
-        {created: [], updated: [], invalidated: [marker2.id], destroyed: []},
-        {created: [], updated: [marker1.id, marker2.id], invalidated: [], destroyed: []}
+        {created: [], updated: [], touched: [marker2.id], destroyed: []},
+        {created: [], updated: [marker1.id, marker2.id], touched: [], destroyed: []}
       ])
 
       events = []
@@ -262,7 +262,7 @@ describe "MarkerLayer", ->
         marker2.destroy()
 
       expect(events).toEqual([
-        {created: [], updated: [], invalidated: [], destroyed: [marker1.id, marker2.id]}
+        {created: [], updated: [], touched: [], destroyed: [marker1.id, marker2.id]}
       ])
 
   describe "::copy", ->

src/display-marker-layer.coffee

@@ -34,19 +34,21 @@ class DisplayMarkerLayer
   onDidDestroy: (callback) ->
     @emitter.on('did-destroy', callback)
 
-  # Public: Subscribe to be notified asynchronously whenever markers are
-  # created, updated, or destroyed on this layer. *Prefer this method for
-  # optimal performance when interacting with layers that could contain large
-  # numbers of markers.*
+  # Public: Subscribe to be notified whenever markers are created, updated,
+  # touched (moved because of a textual change), or destroyed on this layer.
+  # *Prefer this method for optimal performance when interacting with layers
+  # that could contain large numbers of markers.*
   #
   # * `callback` A {Function} that will be called with no arguments when changes
   #   occur on this layer.
   #
-  # Subscribers are notified once, asynchronously when any number of changes
-  # occur in a given tick of the event loop. You should re-query the layer
-  # to determine the state of markers in which you're interested in. It may
-  # be counter-intuitive, but this is much more efficient than subscribing to
-  # events on individual markers, which are expensive to deliver.
+  # Subscribers are notified once when any number of changes occur in this
+  # {MarkerLayer}. The notification gets scheduled either at the end of a
+  # transaction, or synchronously when a marker changes and no transaction is
+  # present. You should re-query the layer to determine the state of markers in
+  # which you're interested in: it may be counter-intuitive, but this is much
+  # more efficient than subscribing to events on individual markers, which are
+  # expensive to deliver.
   #
   # Returns a {Disposable}.
   onDidUpdate: (callback) ->

src/marker-layer.coffee

@@ -33,7 +33,7 @@ class MarkerLayer
 
   constructor: (@delegate, @id, options) ->
     @maintainHistory = options?.maintainHistory ? false
-    @destroyInvalidatedMarkers = options?.destroyInvalidatedMarkers ? false
+    @destroytouchedMarkers = options?.destroytouchedMarkers ? false
     @persistent = options?.persistent ? false
     @emitter = new Emitter
     @index = new MarkerIndex
@@ -42,7 +42,7 @@ class MarkerLayer
     @createdMarkers = new Set
     @destroyedMarkers = new Set
     @updatedMarkers = new Set
-    @invalidatedMarkers = new Set
+    @touchedMarkers = new Set
     @setDisableDidUpdateEvent(false)
     @destroyed = false
     @emitCreateMarkerEvents = false
@@ -208,19 +208,21 @@ class MarkerLayer
   Section: Event subscription
   ###
 
-  # Public: Subscribe to be notified asynchronously whenever markers are
-  # created, updated, or destroyed on this layer. *Prefer this method for
-  # optimal performance when interacting with layers that could contain large
-  # numbers of markers.*
+  # Public: Subscribe to be notified whenever markers are created, updated,
+  # touched (moved because of a textual change), or destroyed on this layer.
+  # *Prefer this method for optimal performance when interacting with layers
+  # that could contain large numbers of markers.*
   #
   # * `callback` A {Function} that will be called with no arguments when changes
   #   occur on this layer.
   #
-  # Subscribers are notified once, asynchronously when any number of changes
-  # occur in a given tick of the event loop. You should re-query the layer
-  # to determine the state of markers in which you're interested in. It may
-  # be counter-intuitive, but this is much more efficient than subscribing to
-  # events on individual markers, which are expensive to deliver.
+  # Subscribers are notified once when any number of changes occur in this
+  # {MarkerLayer}. The notification gets scheduled either at the end of a
+  # transaction, or synchronously when a marker changes and no transaction is
+  # present. You should re-query the layer to determine the state of markers in
+  # which you're interested in: it may be counter-intuitive, but this is much
+  # more efficient than subscribing to events on individual markers, which are
+  # expensive to deliver.
   #
   # Returns a {Disposable}.
   onDidUpdate: (callback) ->
@@ -255,9 +257,9 @@ class MarkerLayer
     invalidated = @index.splice(start, oldExtent, newExtent)
     invalidated.touch.forEach (id) =>
       marker = @markersById[id]
-      @invalidatedMarkers.add(id)
+      @touchedMarkers.add(id)
       if invalidated[marker.getInvalidationStrategy()]?.has(id)
-        if @destroyInvalidatedMarkers
+        if @destroytouchedMarkers
           marker.destroy()
         else
           marker.valid = false
@@ -380,11 +382,11 @@ class MarkerLayer
   emitDidUpdateEvent: ->
     return if @didUpdateEventDisabled
 
-    if @createdMarkers.size > 0 or @destroyedMarkers.size > 0 or @invalidatedMarkers.size > 0 or @updatedMarkers.size > 0
-      event = {created: @createdMarkers, destroyed: @destroyedMarkers, invalidated: @invalidatedMarkers, updated: @updatedMarkers}
+    if @createdMarkers.size > 0 or @destroyedMarkers.size > 0 or @touchedMarkers.size > 0 or @updatedMarkers.size > 0
+      event = {created: @createdMarkers, destroyed: @destroyedMarkers, touched: @touchedMarkers, updated: @updatedMarkers}
       @createdMarkers = new Set
       @destroyedMarkers = new Set
-      @invalidatedMarkers = new Set
+      @touchedMarkers = new Set
       @updatedMarkers = new Set
       @emitter.emit 'did-update', event