Comments. Change up the api a tiny bit.

src/project.coffee

@@ -336,6 +336,12 @@ class Project
 
     deferred.promise
 
+  # Public: Performs a replace across all the specified files in the project.
+  #
+  # * regex: A RegExp to search with
+  # * replacementText: Text to replace all matches of regex with
+  # * filePaths: List of file path strings to run the replace on.
+  # * iterator: A Function callback on each file with replacements. ({filePath, replacements}) ->
   replace: (regex, replacementText, filePaths, iterator) ->
     deferred = Q.defer()
 
@@ -358,7 +364,8 @@ class Project
       task.on 'replace:path-replaced', iterator
 
     for buffer in @buffers
-      buffer.replace(regex, replacementText, iterator)
+      replacements = buffer.replace(regex, replacementText, iterator)
+      iterator({filePath: buffer.getPath(), replacements}) if replacements
 
     inProcessFinished = true
     checkFinished()

src/text-buffer.coffee

@@ -538,7 +538,13 @@ class TextBuffer
       result.lineTextOffset = 0
       iterator(result)
 
-  replace: (regex, replacementText, iterator) ->
+  # Replace all matches of regex with replacementText
+  #
+  # regex: A {RegExp} representing the text to find
+  # replacementText: A {String} representing the text to replace
+  #
+  # Returns the number of replacements made
+  replace: (regex, replacementText) ->
     doSave = !@isModified()
     replacements = 0
 
@@ -549,7 +555,7 @@ class TextBuffer
 
     @save() if doSave
 
-    iterator({filePath: @getPath(), replacements})
+    replacements
 
   # Scans for text in a given range, calling a function on each match.
   #