From 5fc9d9e01afe5ff381ae3662d2629ed8bf4d5618 Mon Sep 17 00:00:00 2001
From: Michael Bolin <mbolin@fb.com>
Date: Tue, 2 Jun 2015 19:14:02 -0400
Subject: [PATCH] Document and test the `cancel()` method on the object
 returned by `atom.workspace.scan()`.

---
 spec/workspace-spec.coffee | 31 +++++++++++++++++++++++++++++++
 src/workspace.coffee       |  3 ++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/spec/workspace-spec.coffee b/spec/workspace-spec.coffee
index 524adde5f..07c543968 100644
--- a/spec/workspace-spec.coffee
+++ b/spec/workspace-spec.coffee
@@ -985,6 +985,37 @@ describe "Workspace", ->
               expect(onPathsSearched.mostRecentCall.args[0]).toBe(
                 numPathsToPretendToSearchInCustomDirectorySearcher + numPathsSearchedInDir2)
 
+          it "can be cancelled when the object returned by scan() has its cancel() method invoked", ->
+            lastCustomDirectorySearchCreated = null
+            class CustomDirectorySearch
+              constructor: ->
+                lastCustomDirectorySearchCreated = this
+                @promise = Promise.resolve()
+              then: (args...) ->
+                @promise.then.apply(@promise, args)
+              cancel: ->
+
+            class CustomDirectorySearcher
+              canSearchDirectory: (directory) -> directory.getPath() is dir1
+              search: (directory, delegate, options) ->
+                new CustomDirectorySearch
+
+            atom.packages.serviceHub.provide(
+              "atom.directory-searcher", "0.1.0", new CustomDirectorySearcher())
+
+            thenable = atom.workspace.scan /aaaa/, ->
+            cancelSpy = spyOn(lastCustomDirectorySearchCreated, 'cancel').andCallThrough()
+            expect(cancelSpy).not.toHaveBeenCalled()
+            thenable.cancel()
+            expect(cancelSpy).toHaveBeenCalled()
+
+            resultOfPromiseSearch = null
+            waitsForPromise ->
+              thenable.then (promiseResult) -> resultOfPromiseSearch = promiseResult
+
+            runs ->
+              expect(resultOfPromiseSearch).toBe('cancelled')
+
           it "will have the side-effect of failing the overall search if it fails", ->
             # Note that hoisting reject in this way is generally frowned upon.
             hoistedReject = null
diff --git a/src/workspace.coffee b/src/workspace.coffee
index f57888777..77706fd69 100644
--- a/src/workspace.coffee
+++ b/src/workspace.coffee
@@ -803,7 +803,8 @@ class Workspace extends Model
   #   * `onPathsSearched` (optional) {Function}
   # * `iterator` {Function} callback on each file found
   #
-  # Returns a `Promise`.
+  # Returns a *thenable* object with a `cancel()` method that will cancel all
+  # of the underlying searches that were started as part of this scan.
   scan: (regex, options={}, iterator) ->
     if _.isFunction(options)
       iterator = options