Merge pull request #7264 from adobe/pflynn/various-cleanups

Various small cleanups - largely docs

Author: ingorichter

src/document/DocumentCommandHandlers.js

@@ -1560,9 +1560,6 @@ define(function (require, exports, module) {
     // Register global commands
     CommandManager.register(Strings.CMD_FILE_OPEN,          Commands.FILE_OPEN, handleFileOpen);
     CommandManager.register(Strings.CMD_ADD_TO_WORKING_SET, Commands.FILE_ADD_TO_WORKING_SET, handleFileAddToWorkingSet);
-    // TODO: (issue #274) For now, hook up File > New to the "new in project" handler. Eventually
-    // File > New should open a new blank tab, and handleFileNewInProject should
-    // be called from a "+" button in the project
     CommandManager.register(Strings.CMD_FILE_NEW_UNTITLED,  Commands.FILE_NEW_UNTITLED, handleFileNew);
     CommandManager.register(Strings.CMD_FILE_NEW,           Commands.FILE_NEW, handleFileNewInProject);
     CommandManager.register(Strings.CMD_FILE_NEW_FOLDER,    Commands.FILE_NEW_FOLDER, handleNewFolderInProject);

src/editor/InlineWidget.js

@@ -97,6 +97,7 @@ define(function (require, exports, module) {
     /**
      * Called once content is parented in the host editor's DOM. Useful for performing tasks like setting
      * focus or measuring content, which require htmlContent to be in the DOM tree.
+     * 
      * IMPORTANT: onAdded() MUST be overridden to call hostEditor.setInlineWidgetHeight() at least once to
      * set the initial height (required to animate it open). The widget will never open otherwise.
      */

src/filesystem/Directory.js

@@ -127,7 +127,9 @@ define(function (require, exports, module) {
     }
 
     /**
-     * Read the contents of a Directory. 
+     * Read the contents of a Directory. If this Directory is under a watch root,
+     * the listing will exclude any items filtered out by the watch root's filter
+     * function.
      *
      * @param {Directory} directory Directory whose contents you want to get
      * @param {function (?string, Array.<FileSystemEntry>=, Array.<FileSystemStats>=, Object.<string, string>=)} callback

src/filesystem/File.js

@@ -149,7 +149,7 @@ define(function (require, exports, module) {
 
         // Request a consistency check if the write is not blind
         if (!options.blind) {
-            options.expectedHash = this._hash; 
+            options.expectedHash = this._hash;
             options.expectedContents = this._contents;
         }
 

src/filesystem/FileSystem.js

@@ -52,6 +52,8 @@
  * to meet these requirements)
  * 
  * FileSystem dispatches the following events:
+ * (NOTE: attach to these events via `FileSystem.on()` - not `$(FileSystem).on()`)
+ * 
  *    change - Sent whenever there is a change in the file system. The handler
  *          is passed up to three arguments: the changed entry and, if that changed entry 
  *          is a Directory, a list of entries added to the directory and a list of entries 
@@ -262,6 +264,8 @@ define(function (require, exports, module) {
             commandName = shouldWatch ? "watchPath" : "unwatchPath";
 
         if (recursiveWatch) {
+            // The impl can watch the entire subtree with one call on the root (we also fall into this case for
+            // unwatch, although that never requires us to do the recursion - see similar final case below)
             if (entry !== watchedRoot.entry) {
                 // Watch and unwatch calls to children of the watched root are
                 // no-ops if the impl supports recursiveWatch
@@ -315,6 +319,8 @@ define(function (require, exports, module) {
                 });
             }, callback);
         } else {
+            // Unwatching never requires enumerating the subfolders (which is good, since after a
+            // delete/rename we may be unable to do so anyway)
             this._enqueueWatchRequest(function (requestCb) {
                 impl.unwatchPath(entry.fullPath, requestCb);
             }, callback);

src/filesystem/impls/appshell/AppshellFileSystem.js

@@ -35,10 +35,27 @@ define(function (require, exports, module) {
 
     var FILE_WATCHER_BATCH_TIMEOUT = 200;   // 200ms - granularity of file watcher changes
 
-    var _changeCallback,            // Callback to notify FileSystem of watcher changes
-        _offlineCallback,           // Callback to notify FileSystem that watchers are offline
-        _changeTimeout,             // Timeout used to batch up file watcher changes
-        _pendingChanges = {};       // Pending file watcher changes
+    /**
+     * Callback to notify FileSystem of watcher changes
+     * @type {?function(string, FileSystemStats=)}
+     */
+    var _changeCallback;
+    
+    /**
+     * Callback to notify FileSystem if watchers stop working entirely
+     * @type {?function()}
+     */
+    var _offlineCallback;
+    
+    /** Timeout used to batch up file watcher changes (setTimeout() return value) */
+    var _changeTimeout;
+    
+    /**
+     * Pending file watcher changes - map from fullPath to flag indicating whether we need to pass stats
+     * to _changeCallback() for this path.
+     * @type {!Object.<string, boolean>}
+     */
+    var _pendingChanges = {};
 
     var _bracketsPath   = FileUtils.getNativeBracketsDirectoryPath(),
         _modulePath     = FileUtils.getNativeModuleDirectoryPath(module),
@@ -48,6 +65,7 @@ define(function (require, exports, module) {
 
     var _isRunningOnWindowsXP = navigator.userAgent.indexOf("Windows NT 5.") >= 0;
 
+    
     // If the connection closes, notify the FileSystem that watchers have gone offline.
     $(_nodeDomain.connection).on("close", function (event, promise) {
         if (_offlineCallback) {
@@ -105,7 +123,7 @@ define(function (require, exports, module) {
         if (event === "change") {
             // Only register change events if filename is passed
             if (filename) {
-                // an existing file was created; stats are needed
+                // an existing file was modified; stats are needed
                 change = path + filename;
                 _enqueueChange(change, true);
             }

src/nls/fa-ir/urls.js

@@ -26,5 +26,5 @@
 
 define({
     // Relative to the samples folder     
-    "WEB_PLATFORM_DOCS_LICENSE" : "http://creativecommons.org/licenses/by/3.0/deed.fa",
+    "WEB_PLATFORM_DOCS_LICENSE" : "http://creativecommons.org/licenses/by/3.0/deed.fa"
 });

src/project/ProjectManager.js

@@ -103,7 +103,7 @@ define(function (require, exports, module) {
      *    https://github.com/adobe/brackets/issues/6781
      * @type {RegExp}
      */
-    var _exclusionListRegEx = /\.pyc$|^\.git$|^\.gitmodules$|^\.svn$|^\.DS_Store$|^Thumbs\.db$|^\.hg$|^CVS$|^\.hgtags$|^\.c9revisions|^\.SyncArchive|^\.SyncID|^\.SyncIgnore|\~$/;
+    var _exclusionListRegEx = /\.pyc$|^\.git$|^\.gitmodules$|^\.svn$|^\.DS_Store$|^Thumbs\.db$|^\.hg$|^CVS$|^\.hgtags$|^\.idea$|^\.c9revisions$|^\.SyncArchive$|^\.SyncID$|^\.SyncIgnore$|\~$/;
 
     /**
      * @private

src/project/SidebarView.js

@@ -51,7 +51,7 @@ define(function (require, exports, module) {
         EditorManager       = require("editor/EditorManager"),
         Global              = require("utils/Global"),
         Resizer             = require("utils/Resizer"),
-        _                   = require("thirdparty/lodash");        
+        _                   = require("thirdparty/lodash");
 
     // These vars are initialized by the htmlReady handler
     // below since they refer to DOM elements

src/utils/Resizer.js

@@ -111,7 +111,8 @@ define(function (require, exports, module) {
     }
 
     /**
-     * Adds resizing capabilities to a given html element.
+     * Adds resizing and (optionally) expand/collapse capabilities to a given html element. The element's size
+     * & visibility are automatically saved & restored as a view-state preference.
      *
      * Resizing can be configured in two directions:
      *  - Vertical ("vert"): Resizes the height of the element
@@ -130,7 +131,8 @@ define(function (require, exports, module) {
      *  - panelExpanded: When the panel gets expanded (or shown). Passed the initial size.
      *      May occur without any resize events.
      *
-     * @param {!DOMNode} element DOM element which should be made resizable.
+     * @param {!DOMNode} element DOM element which should be made resizable. Must have an id attribute, for
+     *                          use as a preferences key.
      * @param {!string} direction Direction of the resize action: one of the DIRECTION_* constants.
      * @param {!string} position Which side of the element can be dragged: one of the POSITION_* constants
      *                          (TOP/BOTTOM for vertical resizing or LEFT/RIGHT for horizontal).
@@ -159,6 +161,11 @@ define(function (require, exports, module) {
             resizerCSSPosition  = direction === DIRECTION_HORIZONTAL ? "left" : "top",
             contentSizeFunction = direction === DIRECTION_HORIZONTAL ? $resizableElement.width : $resizableElement.height;
 
+        if (!elementID) {
+            console.error("Resizable panels must have a DOM id to use as a preferences key:", element);
+            return;
+        }
+        
         if (minSize === undefined) {
             minSize = DEFAULT_MIN_SIZE;
         }