Dispatch a FileSystem "change" event even when a dir change yields empty

added/removed lists - because there's a delay between the change occurring
and the time we re-read the dir contents in response, we might see
back-to-back changes (e.g. a delete-recreate pair) as a no-op even though
something definitely changed. See #6609 for an example bug.

Updated docs to clarify the two different special cases of directory change
events. (Also contains an unrelated small docs improvement in FileUtils).

ProjectManager already responds to this special case the way we'd want - it
calls FileSyncManager and then does nothing else - so no code changes
needed there.

src/file/FileUtils.js

@@ -45,8 +45,8 @@ define(function (require, exports, module) {
      * Asynchronously reads a file as UTF-8 encoded text.
      * @param {!File} file File to read
      * @return {$.Promise} a jQuery promise that will be resolved with the 
-     *  file's text content plus its timestamp, or rejected with a FileSystemError if
-     *  the file can not be read.
+     *  file's text content plus its timestamp, or rejected with a FileSystemError string
+     *  constant if the file can not be read.
      */
     function readAsText(file) {
         var result = new $.Deferred();
@@ -77,7 +77,7 @@ define(function (require, exports, module) {
      *      errors---which can be triggered if the actual file contents differ from 
      *      the FileSystem's last-known contents---should be ignored.
      * @return {$.Promise} a jQuery promise that will be resolved when
-     * file writing completes, or rejected with a FileSystemError.
+     * file writing completes, or rejected with a FileSystemError string constant.
      */
     function writeText(file, text, allowBlindWrite) {
         var result = new $.Deferred(),

src/filesystem/FileSystem.js

@@ -46,6 +46,11 @@
  *          *  a File - the contents of the file have changed, and should be reloaded.
  *          *  a Directory - an immediate child of the directory has been added, removed,
  *             or renamed/moved. Not triggered for "grandchildren".
+ *               - If the added & removed arguments are null, we don't know what was added/removed:
+ *                 clients should assume the whole subtree may have changed.
+ *               - If the added & removed arguments are 0-length, there's no net change in the set
+ *                 of files but a file may have been replaced: clients should assume the contents
+ *                 of any immediate child file may have changed.
  *          *  null - a 'wholesale' change happened, and you should assume everything may
  *             have changed.
  *          For changes made externally, there may be a significant delay before a "change" event
@@ -777,9 +782,11 @@ define(function (require, exports, module) {
             } else {
                 this._handleDirectoryChange(entry, function (added, removed) {
                     entry._stat = stat;
-                    if (!(added && added.length === 0 && removed && removed.length === 0)) {
-                        this._fireChangeEvent(entry, added, removed);
-                    }
+
+                    // We send a change even if added & removed are both length zero-length. Something may still have changed,
+                    // e.g. a file may have been quickly removed & re-added before we got a chance to reread the directory
+                    // listing.
+                    this._fireChangeEvent(entry, added, removed);
                 }.bind(this));
             }
         }