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

Big bag o' minor code cleanups & JSLint fixes
This commit is contained in:
Randy Edmunds 2012-11-08 10:44:35 -08:00
Родитель 633dca824c 71bf017d79
Коммит f419f46033
14 изменённых файлов: 126 добавлений и 81 удалений

Просмотреть файл

@ -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);

Просмотреть файл

@ -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
*/

Просмотреть файл

@ -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

Просмотреть файл

@ -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);

Просмотреть файл

@ -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);
});

Просмотреть файл

@ -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) {

Просмотреть файл

@ -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 {

Просмотреть файл

@ -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");

Просмотреть файл

@ -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) {

Просмотреть файл

@ -33,17 +33,16 @@
* "bottom-resizer", "left-resizer" and "right-resizer" classes control the
* position of the resizer on the element.
*
* An element can be made resizable at any time using the `makeResizable` API
* An element can be made resizable at any time using the `makeResizable()` API.
* Panel sizes are saved via preferences and restored when the DOM node becomes resizable
* again in a subsequent launch.
*
* The resizable elements trigger a panelResizeStart, panelResizeUpdate and panelResizeEnd
* event that can be used to create performance optimizations (such as hiding/showing elements
* while resizing), custom or internal resizes and save the final resized value into local
* storage for example.
* while resizing), custom layout logic, etc. See makeResizable() for details on the events.
*
* A resizable element can be collapsed/expanded using the `show`, `hide` and `toggle` APIs
*
* The resizable elements trigger a panelCollapsed and panelExpanded event when the panel toggles
* between visible and invisible
* A resizable element can be collapsed/expanded using the `show`, `hide` and `toggle` APIs or
* via user action. This triggers panelCollapsed/panelExpanded events - see makeResizable().
*/
define(function (require, exports, module) {
"use strict";
@ -122,20 +121,25 @@ define(function (require, exports, module) {
* - Left ("left") or right ("right") for horizontal resizing
*
* A resizable element triggers the following events while resizing:
* - panelResizeStart: When the resize starts
* - panelResizeUpdate: When the resize gets updated
* - panelResizeEnds: When the resize ends
* - panelCollapsed: When the panel gets collapsed (or hidden)
* - panelExpanded: When the panel gets expanded (or shown)
* - panelResizeStart: When the resize starts. Passed the new size.
* - panelResizeUpdate: When the resize gets updated. Passed the new size.
* - panelResizeEnd: When the resize ends. Passed the final size.
* - panelCollapsed: When the panel gets collapsed (or hidden). Passed the last size
* before collapse. May occur without any resize events.
* - panelExpanded: When the panel gets expanded (or shown). Passed the initial size.
* May occur without any resize events.
* TODO (#2079): Spurious resize events may occur after collapse or before expand, reporting
* the wrong size. If a panel is currently hidden (display:none), ignore these events.
*
* @param {DOMNode} element Html element which should be made resizable.
* @param {string} direction The direction of the resize action. Must be "horz" or "vert".
* @param {string} position The position of the resizer on the element. Can be "top" or "bottom"
* for vertical resizing and "left" or "right" for horizontal resizing.
* @param {int} minSize Minimum size (width or height) of the element.
* @param {boolean} collapsible True indicates the panel is collapsible on double click
* on the resizer.
* @param {string} forcemargin Classes which margins need to be pushed when the element resizes
* @param {!DOMNode} element DOM element which should be made resizable.
* @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).
* @param {?number} minSize Minimum size (width or height) of the element. Defaults to 0.
* @param {?boolean} collapsible Indicates the panel is collapsible on double click on the
* resizer. Defaults to false.
* @param {?string} forcemargin CSS selector indicating element whose margin-left should be locked to
* the resizable elemnt's size.
*/
function makeResizable(element, direction, position, minSize, collapsible, forcemargin) {
@ -182,7 +186,10 @@ define(function (require, exports, module) {
}
forceMargins(elementSize);
// Vertical resize affects editor directly; horizontal resize could change height of top toolbar
EditorManager.resizeEditor();
$element.trigger("panelExpanded", [elementSize]);
_prefs.setValue(elementID, elementPrefs);
});
@ -204,7 +211,10 @@ define(function (require, exports, module) {
}
forceMargins(0);
// Vertical resize affects editor directly; horizontal resize could change height of top toolbar
EditorManager.resizeEditor();
$element.trigger("panelCollapsed", [elementSize]);
_prefs.setValue(elementID, elementPrefs);
});
@ -269,6 +279,7 @@ define(function (require, exports, module) {
$element.trigger("panelResizeStart", [elementSizeFunction.apply($element)]);
}
// Vertical resize affects editor directly; horizontal resize could change height of top toolbar
EditorManager.resizeEditor();
}

Просмотреть файл

@ -115,7 +115,7 @@ define(function (require, exports, module) {
function offsetInToken(ctx) {
var offset = ctx.pos.ch - ctx.token.start;
if (offset < 0) {
console.log("CodeHintUtils: _offsetInToken - Invalid context: the pos what not in the current token!");
console.log("CodeHintUtils: _offsetInToken - Invalid context: pos not in the current token!");
}
return offset;
}

Просмотреть файл

@ -192,7 +192,7 @@ define(function (require, exports, module) {
var updateSelectionTriangle = function () {
var selectionMarkerHeight = $selectionMarker.height(),
selectionMarkerOffset = $selectionMarker.offset(),
selectionMarkerOffset = $selectionMarker.offset(), // offset relative to *document*
scrollerOffset = $scrollerElement.offset(),
triangleHeight = $selectionTriangle.outerHeight(),
scrollerTop = scrollerOffset.top,

Просмотреть файл

@ -253,38 +253,38 @@ define(function (require, exports, module) {
});
describe("escapes", function() {
describe("escapes", function () {
beforeEach(function () {
init(this, escapesCssFileEntry);
});
it("should remove simple backslashes for simple characters", function() {
it("should remove simple backslashes for simple characters", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[0].selector).toEqual(".simple");
});
it("should remove simple backslashes with escaped characters", function() {
it("should remove simple backslashes with escaped characters", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[1].selector).toEqual(".not\\so|simple?");
});
it("should parse '\\XX ' as a single character", function() {
it("should parse '\\XX ' as a single character", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[2].selector).toEqual(".twodigits");
});
it("should parse '\\XXXX ' as a single character", function() {
it("should parse '\\XXXX ' as a single character", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[3].selector).toEqual(".fourdigits");
});
it("should parse '\\XXXXXX' as a single character", function() {
it("should parse '\\XXXXXX' as a single character", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[4].selector).toEqual(".sixdigits");
});
it("should not trim end spaces", function() {
it("should not trim end spaces", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[5].selector).toEqual(".two-digit-endspace");
@ -292,30 +292,30 @@ define(function (require, exports, module) {
expect(selectors[6].selector).toEqual(".four-digit-endspace");
selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[7].selector).toEqual(".six-digit-endspace");
expect(selectors[7].selector).toEqual(".six-digit-endspace");
});
it("should detect all combinations", function() {
it("should detect all combinations", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[8].selector).toEqual(".mixin-it-all");
});
it("should parse '\\AX' as AX", function() {
it("should parse '\\AX' as AX", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[9].selector).toEqual(".two-wi74out-space");
});
it("should parse '\\AXXX' as AXXX", function() {
it("should parse '\\AXXX' as AXXX", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[10].selector).toEqual(".four-n0085-space");
});
it("should replace out of range characters with <EFBFBD>", function() {
it("should replace out of range characters with U+FFFD", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[11].selector).toEqual(".<EFBFBD>ut<EFBFBD>frange");
expect(selectors[11].selector).toEqual(".\uFFFDut\uFFFDfrange");
});
it("should parse everything less does", function() {
it("should parse everything less does", function () {
var selectors = CSSUtils.extractAllSelectors(this.fileCssContent);
expect(selectors[12].selector).toEqual(".escape|random|char");
expect(selectors[13].selector).toEqual(".mixin!tUp");

Просмотреть файл

@ -650,6 +650,8 @@ define(function (require, exports, module) {
describe("Bi-directional Editor Synchronizing", function () {
// For these tests we *deliberately* use Editor._codeMirror instead of Document to make edits,
// in order to test Editor->Document syncing (instead of Document->Editor).
it("should not add an inline document to the working set without being edited", function () {
initInlineTest("test1.html", 0);