From df3e535f39074d401441cfbb703feb2283831dd0 Mon Sep 17 00:00:00 2001 From: Peter Flynn Date: Mon, 5 Nov 2012 15:13:30 -0800 Subject: [PATCH] Tweaks to docs in various files: clarifications & added/fixed type annotations. Fix lots of JSLint errors in CSSUtils-test. Remove unused dependencies in WorkingSetView. --- src/command/KeyBindingManager.js | 2 +- src/command/Menus.js | 12 +++++--- src/document/DocumentManager.js | 18 ++++++++--- src/editor/Editor.js | 4 +-- src/editor/InlineTextEditor.js | 6 ++-- src/file/NativeFileSystem.js | 41 +++++++++++++++++-------- src/language/HTMLUtils.js | 29 ++++++++++------- src/project/WorkingSetView.js | 2 -- src/utils/Async.js | 8 ++--- src/utils/Resizer.js | 6 ++-- src/utils/TokenUtils.js | 2 +- src/utils/ViewUtils.js | 2 +- test/spec/CSSUtils-test.js | 28 ++++++++--------- test/spec/InlineEditorProviders-test.js | 2 ++ 14 files changed, 98 insertions(+), 64 deletions(-) diff --git a/src/command/KeyBindingManager.js b/src/command/KeyBindingManager.js index f3d713ed7..9992db1cb 100644 --- a/src/command/KeyBindingManager.js +++ b/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); diff --git a/src/command/Menus.js b/src/command/Menus.js index 22da336b2..129e67e30 100644 --- a/src/command/Menus.js +++ b/src/command/Menus.js @@ -408,11 +408,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 */ diff --git a/src/document/DocumentManager.js b/src/document/DocumentManager.js index 8d967c8f7..7a79a0522 100644 --- a/src/document/DocumentManager.js +++ b/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: combine workingSetSort & workingSetReorder since they don't convey different 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 diff --git a/src/editor/Editor.js b/src/editor/Editor.js index bff7ab362..d54c36651 100644 --- a/src/editor/Editor.js +++ b/src/editor/Editor.js @@ -831,7 +831,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(); @@ -841,7 +841,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); diff --git a/src/editor/InlineTextEditor.js b/src/editor/InlineTextEditor.js index d767dd522..aa4515c49 100644 --- a/src/editor/InlineTextEditor.js +++ b/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); }); diff --git a/src/file/NativeFileSystem.js b/src/file/NativeFileSystem.js index 9b6baa5d8..8a8c07089 100644 --- a/src/file/NativeFileSystem.js +++ b/src/file/NativeFileSystem.js @@ -57,8 +57,8 @@ define(function (require, exports, module) { * @param {string} title * @param {string} initialPath * @param {Array.} fileTypes - * @param {function(...)} successCallback - * @param {function(...)} errorCallback + * @param {!function(Array.)} 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.)} successCallback + * @param {!function(FileError|number)} errorCallback (TODO #2057: should consistently pass a FileError) * @returns {Array.} */ NativeFileSystem.DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) { diff --git a/src/language/HTMLUtils.js b/src/language/HTMLUtils.js index 79acaa932..c5cda6e26 100644 --- a/src/language/HTMLUtils.js +++ b/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 : * className:tag string:"" * @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