Merge pull request #2058 from adobe/pflynn/docs-cleanups

Big bag o' minor code cleanups & JSLint fixes

src/command/KeyBindingManager.js

@@ -421,7 +421,7 @@ define(function (require, exports, module) {
         if (Array.isArray(keyBindings)) {
             var keyBinding;
             results = [];
-                                            
+
             keyBindings.forEach(function (keyBindingRequest) {
                 keyBinding = _addBinding(commandID, keyBindingRequest, keyBindingRequest.platform);
 

src/command/Menus.js

@@ -427,11 +427,13 @@ define(function (require, exports, module) {
      *      Pass Menus.DIVIDER for a menu divider, or just call addMenuDivider() instead.
      * @param {?string | Array.<{key: string, platform: string}>}  keyBindings - register one
      *      one or more key bindings to associate with the supplied command.
-     * @param {?string} position - constant defining the position of new the MenuItem relative
-     *      to other MenuItems. Default is LAST.  (see Insertion position constants). 
-     * @param {?string} relativeID - id of command or menu section (future: sub-menu) that 
-     *      the new menuItem will be positioned relative to. Required for all position constants
-     *      except FIRST and LAST.
+     * @param {?string} position - constant defining the position of new MenuItem relative to
+     *      other MenuItems. Values:
+     *          - With no relativeID, use Menus.FIRST or LAST (default is LAST)
+     *          - Relative to a command id, use BEFORE or AFTER (required)
+     *          - Relative to a MenuSection, use FIRST_IN_SECTION or LAST_IN_SECTION (required)
+     * @param {?string} relativeID - command id OR one of the MenuSection.* constants. Required
+     *      for all position constants except FIRST and LAST.
      *
      * @return {MenuItem} the newly created MenuItem
      */

src/document/DocumentManager.js

@@ -51,23 +51,29 @@
  * any unsaved changes.
  *
  * This module dispatches several events:
+ *
  *    - dirtyFlagChange -- When any Document's isDirty flag changes. The 2nd arg to the listener is the
  *      Document whose flag changed.
  *    - documentSaved -- When a Document's changes have been saved. The 2nd arg to the listener is the 
  *      Document that has been saved.
+ *
  *    - currentDocumentChange -- When the value of getCurrentDocument() changes.
+ *
+ *    To listen for working set changes, you must listen to *all* of these events:
  *    - workingSetAdd -- When a file is added to the working set (see getWorkingSet()). The 2nd arg
  *      to the listener is the added FileEntry.
- *    - workingSetAddList -- When a list of files are added to the working set (e.g. project open, multiple file open).
+ *    - workingSetAddList -- When multiple files are added to the working set (e.g. project open, multiple file open).
  *      The 2nd arg to the listener is the array of added FileEntry objects.
  *    - workingSetRemove -- When a file is removed from the working set (see getWorkingSet()). The
  *      2nd arg to the listener is the removed FileEntry.
- *    - workingSetRemoveList -- When a list of files is to be removed from the working set (e.g. project close).
+ *    - workingSetRemoveList -- When multiple files are removed from the working set (e.g. project close).
  *      The 2nd arg to the listener is the array of removed FileEntry objects.
+ *    - workingSetReorder -- When the indexes of 2 files are swapped. Listener receives no arguments.
+ *    - workingSetSort -- When the workingSet array is sorted. Listener receives no arguments.
+ *      TODO (#2076): combine workingSetSort & workingSetReorder since they convey nearly identical information.
+ *
  *    - fileNameChange -- When the name of a file or folder has changed. The 2nd arg is the old name.
  *      The 3rd arg is the new name.
- *    - workingSetReorder -- When the indexes of 2 files are swapped during a drag and drop order.
- *    - workingSetSort -- When the workingSet array is sorted.
  *
  * These are jQuery events, so to listen for them you do something like this:
  *    $(DocumentManager).on("eventname", handler);
@@ -962,6 +968,8 @@ define(function (require, exports, module) {
      * Returns the existing open Document for the given file, or null if the file is not open ('open'
      * means referenced by the UI somewhere). If you will hang onto the Document, you must addRef()
      * it; see {@link getDocumentForPath()} for details.
+     * @param {!string} fullPath
+     * @return {?Document}
      */
     function getOpenDocumentForPath(fullPath) {
         return _openDocuments[fullPath];
@@ -978,6 +986,8 @@ define(function (require, exports, module) {
      *
      * FUTURE: Instead of an explicit notify, we should eventually listen for deletion events on some
      * sort of "project file model," making this just a private event handler.
+     *
+     * @param {!FileEntry} file
      */
     function notifyFileDeleted(file) {
         // First ensure it's not currentDocument, and remove from working set

src/editor/Editor.js

@@ -828,7 +828,7 @@ define(function (require, exports, module) {
 
     /**
      * Gets the root DOM node of the editor.
-     * @returns {Object} The editor's root DOM node.
+     * @returns {!HTMLDivElement} The editor's root DOM node.
      */
     Editor.prototype.getRootElement = function () {
         return this._codeMirror.getWrapperElement();
@@ -838,7 +838,7 @@ define(function (require, exports, module) {
      * Gets the lineSpace element within the editor (the container around the individual lines of code).
      * FUTURE: This is fairly CodeMirror-specific. Logic that depends on this may break if we switch
      * editors.
-     * @returns {Object} The editor's lineSpace element.
+     * @returns {!HTMLDivElement} The editor's lineSpace element.
      */
     Editor.prototype._getLineSpaceElement = function () {
         return $(".CodeMirror-lines", this.getScrollerElement()).children().get(0);

src/editor/InlineTextEditor.js

@@ -238,12 +238,12 @@ define(function (require, exports, module) {
         this.editors.push(inlineInfo.editor);
         container.appendChild(wrapperDiv);
 
-        // Size editor to content whenever it changes (via edits here or any other view of the doc)
+        // Size editor to content whenever text changes (via edits here or any other view of the doc: Editor
+        // fires "change" any time its text changes, regardless of origin)
         $(inlineInfo.editor).on("change", function () {
             self.sizeInlineWidgetToContents();
 
-            // And update line number since a change to the Editor equals a change to the Document,
-            // which may mean a change to the line range too
+            // Changes above the inline range could change our line number, so update label
             $lineNumber.text(inlineInfo.editor.getFirstVisibleLine() + 1);
         });
 

src/file/NativeFileSystem.js

@@ -57,8 +57,8 @@ define(function (require, exports, module) {
          * @param {string} title
          * @param {string} initialPath
          * @param {Array.<string>} fileTypes
-         * @param {function(...)} successCallback
-         * @param {function(...)} errorCallback
+         * @param {!function(Array.<string>)} successCallback
+         * @param {!function(number)} errorCallback (TODO #2057: should this pass a FileError?)
          * @constructor
          */
         showOpenDialog: function (allowMultipleSelection,
@@ -90,9 +90,9 @@ define(function (require, exports, module) {
 
         /** requestNativeFileSystem
          *
-         * @param {string} path
-         * @param {function(...)} successCallback
-         * @param {function(...)} errorCallback
+         * @param {!string} path
+         * @param {!function(DirectoryEntry)} successCallback
+         * @param {!function(number)} errorCallback (TODO #2057: should pass a FileError)
          */
         requestNativeFileSystem: function (path, successCallback, errorCallback) {
             brackets.fs.stat(path, function (err, data) {
@@ -106,6 +106,11 @@ define(function (require, exports, module) {
             });
         },
 
+        /**
+         * Converts a brackets.fs.ERR_* error code to a FileError.* error code
+         * @param {number} nativeErr
+         * @return {number}
+         */
         _nativeToFileError: function (nativeErr) {
             var error;
 
@@ -246,6 +251,10 @@ define(function (require, exports, module) {
         // http://www.w3.org/TR/2011/WD-file-system-api-20110419/#widl-Entry-remove
     };
 
+    /**
+     * @param {!function(Metadata)} successCallBack
+     * @param {!function(number)} errorCallback (TODO #2057: should pass a FileError)
+     */
     NativeFileSystem.Entry.prototype.getMetadata = function (successCallBack, errorCallback) {
         brackets.fs.stat(this.fullPath, function (err, stat) {
             if (err === brackets.fs.NO_ERROR) {
@@ -285,8 +294,8 @@ define(function (require, exports, module) {
     /**
      * Creates a new FileWriter associated with the file that this FileEntry represents.
      *
-     * @param {function (FileWriter)} successCallback
-     * @param {function (FileError)} errorCallback
+     * @param {!function(FileWriter)} successCallback
+     * @param {!function(number)} errorCallback (TODO #2057: should pass a FileError)
      */
     NativeFileSystem.FileEntry.prototype.createWriter = function (successCallback, errorCallback) {
         var fileEntry = this;
@@ -398,8 +407,8 @@ define(function (require, exports, module) {
     /**
      * Obtains the File objecte for a FileEntry object
      *
-     * @param {function(...)} successCallback
-     * @param {function(...)} errorCallback
+     * @param {!function(File)} successCallback
+     * @param {!function(FileError)} errorCallback
      */
     NativeFileSystem.FileEntry.prototype.file = function (successCallback, errorCallback) {
         var newFile = new NativeFileSystem.File(this);
@@ -516,6 +525,12 @@ define(function (require, exports, module) {
         return "[DirectoryEntry " + this.fullPath + "]";
     };
 
+    /**
+     * @param {!string} path
+     * @param {!{create:?boolean, exclusive:?boolean}} options
+     * @param {!function(DirectoryEntry)} successCallback
+     * @param {!function(FileError|number)} errorCallback (TODO #2057: should consistently pass a FileError)
+     */
     NativeFileSystem.DirectoryEntry.prototype.getDirectory = function (path, options, successCallback, errorCallback) {
         var directoryFullPath = path;
 
@@ -621,8 +636,8 @@ define(function (require, exports, module) {
      *        to attempt to create a file whose immediate parent does not yet
      *        exist.
      * @param {!{create:?boolean, exclusive:?boolean}} options
-     * @param {function (FileEntry)} successCallback
-     * @param {function (number)} errorCallback
+     * @param {!function(FileEntry)} successCallback
+     * @param {!function(FileError|number)} errorCallback  (TODO #2057: should consistently pass a FileError)
      */
     NativeFileSystem.DirectoryEntry.prototype.getFile = function (path, options, successCallback, errorCallback) {
         var fileFullPath = path;
@@ -716,8 +731,8 @@ define(function (require, exports, module) {
 
     /** readEntries
      *
-     * @param {function(...)} successCallback
-     * @param {function(...)} errorCallback
+     * @param {!function(Array.<Entry>)} successCallback
+     * @param {!function(FileError|number)} errorCallback (TODO #2057: should consistently pass a FileError)
      * @returns {Array.<Entry>}
      */
     NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) {

src/language/HTMLUtils.js

@@ -114,13 +114,16 @@ define(function (require, exports, module) {
 
     /**
      * Creates a tagInfo object and assures all the values are entered or are empty strings
-     * @param {string} tokenType what is getting edited and should be hinted
-     * @param {number} offset where the cursor is for the part getting hinted
-     * @param {string} tagName The name of the tag
-     * @param {string} attrName The name of the attribute
-     * @param {string} attrValue The value of the attribute
-     * @return {{tagName:string, attr{name:string, value:string}, hint:{type:{string}, offset{number}}}}
-     *              A tagInfo object with some context about the current tag hint.            
+     * @param {string=} tokenType what is getting edited and should be hinted
+     * @param {number=} offset where the cursor is for the part getting hinted
+     * @param {string=} tagName The name of the tag
+     * @param {string=} attrName The name of the attribute
+     * @param {string=} attrValue The value of the attribute
+     * @return {{tagName:string,
+     *           attr:{name:string, value:string, valueAssigned:boolean, quoteChar:string, hasEndQuote:boolean},
+     *           position:{tokenType:string, offset:number}
+     *         }}
+     *         A tagInfo object with some context about the current tag hint.
      */
     function createTagInfo(tokenType, offset, tagName, attrName, attrValue, valueAssigned, quoteChar, hasEndQuote) {
         return { tagName: tagName || "",
@@ -223,7 +226,7 @@ define(function (require, exports, module) {
     }
 
     /**
-     * Figure out if we're in a tag, and if we are return info about what to hint about it
+     * Figure out if we're in a tag, and if we are return info about it
      * An example token stream for this tag is <span id="open-files-disclosure-arrow"></span> : 
      *      className:tag       string:"<span"
      *      className:          string:" "
@@ -233,13 +236,15 @@ define(function (require, exports, module) {
      *      className:tag       string:"></span>"
      * @param {Editor} editor An instance of a Brackets editor
      * @param {{ch: number, line: number}} constPos  A CM pos (likely from editor.getCursor())
-     * @return {{tagName:string, attr{name:string, value:string}, hint:{type:{string}, offset{number}}}}
-     *              A tagInfo object with some context about the current tag hint.
+     * @return {{tagName:string,
+     *           attr:{name:string, value:string, valueAssigned:boolean, quoteChar:string, hasEndQuote:boolean},
+     *           position:{tokenType:string, offset:number}
+     *         }}
+     *         A tagInfo object with some context about the current tag hint.
      */
     function getTagInfo(editor, constPos) {
         // We're going to be changing pos a lot, but we don't want to mess up
         // the pos the caller passed in so we use extend to make a safe copy of it.	
-        // This is what pass by value in c++ would do.	
         var pos = $.extend({}, constPos),
             ctx = TokenUtils.getInitialContext(editor._codeMirror, pos),
             tempCtx = null,
@@ -402,6 +407,7 @@ define(function (require, exports, module) {
      * Returns an Array of info about all <style> blocks in the given Editor's HTML document (assumes
      * the Editor contains HTML text).
      * @param {!Editor} editor
+     * @return {Array.<{start:{line:number, ch:number}, end:{line:number, ch:number}, text:string}>}
      */
     function findStyleBlocks(editor) {
         // Start scanning from beginning of file
@@ -415,6 +421,7 @@ define(function (require, exports, module) {
             if (inStyleBlock) {
                 // Check for end of this <style> block
                 if (ctx.token.state.mode !== "css") {
+                    // currentStyleBlock.end is already set to pos of the last CSS token by now
                     currentStyleBlock.text = editor.document.getRange(currentStyleBlock.start, currentStyleBlock.end);
                     inStyleBlock = false;
                 } else {

src/project/WorkingSetView.js

@@ -38,9 +38,7 @@ define(function (require, exports, module) {
         CommandManager        = require("command/CommandManager"),
         Commands              = require("command/Commands"),
         Menus                 = require("command/Menus"),
-        EditorManager         = require("editor/EditorManager"),
         FileViewController    = require("project/FileViewController"),
-        NativeFileSystem      = require("file/NativeFileSystem").NativeFileSystem,
         ViewUtils             = require("utils/ViewUtils");
 
 

src/utils/Async.js

@@ -200,13 +200,13 @@ define(function (require, exports, module) {
     }
 
     /**
-     * Executes a series of tasks sequentially in time-slices less than maxBlockingTime.
+     * Executes a series of synchronous tasks sequentially spread over time-slices less than maxBlockingTime.
      * Processing yields by idleTime between time-slices.
      * 
      * @param {!Array.<*>} items
-     * @param {!function(*, number):Promise} fnProcessItem
-     * @param {!number} maxBlockingTime
-     * @param {!number} idleTime
+     * @param {!function(*, number)} fnProcessItem  Function that synchronously processes one item
+     * @param {number=} maxBlockingTime
+     * @param {number=} idleTime
      * @return {$.Promise}
      */
     function doSequentiallyInBackground(items, fnProcessItem, maxBlockingTime, idleTime) {