From 40a140ffdc44603978e90bec8388ebd0721df3b6 Mon Sep 17 00:00:00 2001 From: Pluto Date: Thu, 7 Nov 2024 18:10:16 +0530 Subject: [PATCH 1/6] docs: fix docusaurus build fail issue --- src/JSUtils/ScopeManager.js | 3 +-- src/command/KeyBindingManager.js | 5 +++-- src/widgets/Dialogs.js | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/JSUtils/ScopeManager.js b/src/JSUtils/ScopeManager.js index 572ba0e434..b74267e946 100644 --- a/src/JSUtils/ScopeManager.js +++ b/src/JSUtils/ScopeManager.js @@ -1511,8 +1511,7 @@ define(function (require, exports, module) { /** * Called each time the file associated with the active editor changes. * Marks the file as being dirty. - * - * @param {{line:number, ch: number}} changeList {from: {line:number, ch: number}, to: {line:number, ch:number}} + * @param {{line:number, ch: number}} changeList - An object representing the change range with `from` and `to` properties, each containing `line` and `ch` numbers. */ function handleFileChange(changeList) { isDocumentDirty = true; diff --git a/src/command/KeyBindingManager.js b/src/command/KeyBindingManager.js index a68841cf43..a57fd6565a 100644 --- a/src/command/KeyBindingManager.js +++ b/src/command/KeyBindingManager.js @@ -889,9 +889,10 @@ define(function (require, exports, module) { /** * Returns a copy of the current key map. If the optional 'defaults' parameter is true, * then a copy of the default key map is returned. + * In the default keymap each key is associated with an object containing `commandID`, `key`, and `displayKey`. * * @param {boolean=} defaults true if the caller wants a copy of the default key map. Otherwise, the current active key map is returned. - * @return {!Object.} + * @return {Object} */ function getKeymap(defaults) { return $.extend({}, defaults ? _defaultKeyMap : _keyMap); @@ -1239,7 +1240,7 @@ define(function (require, exports, module) { document.body.classList.add('hide-cursor'); } } - + /** * Handles a given keydown event, checking global hooks first before * deciding to handle it ourselves. diff --git a/src/widgets/Dialogs.js b/src/widgets/Dialogs.js index cf24836dab..0fd7ea573a 100644 --- a/src/widgets/Dialogs.js +++ b/src/widgets/Dialogs.js @@ -468,7 +468,7 @@ define(function (require, exports, module) { * @param {string} dlgClass A class name identifier for the dialog. Typically one of DefaultDialogs.* * @param {string=} title The title of the dialog. Can contain HTML markup. Defaults to "". * @param {string=} message The message to display in the dialog. Can contain HTML markup. Defaults to "". - * @param {Array.<{className: string, id: string, text: string, tooltip:string}>=} buttons An array of buttons where each button + * @param {Array.} buttons An array of buttons where each button * has a class, id tooltip, and text property. The id is used in "data-button-id". Defaults to a single Ok button. * Typically className is one of DIALOG_BTN_CLASS_*, id is one of DIALOG_BTN_* * @param {boolean=} autoDismiss Whether to automatically dismiss the dialog when one of the buttons From 010dfdc2a2c3bfb9b2b680c00d07b562f9351b2e Mon Sep 17 00:00:00 2001 From: Pluto Date: Thu, 7 Nov 2024 18:21:55 +0530 Subject: [PATCH 2/6] docs: update markdown files, after build fail issue fix --- docs/API-Reference/JSUtils/ScopeManager.md | 2 +- docs/API-Reference/command/KeyBindingManager.md | 3 ++- docs/API-Reference/widgets/Dialogs.md | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/API-Reference/JSUtils/ScopeManager.md b/docs/API-Reference/JSUtils/ScopeManager.md index c584ac50d9..94d67ef0ba 100644 --- a/docs/API-Reference/JSUtils/ScopeManager.md +++ b/docs/API-Reference/JSUtils/ScopeManager.md @@ -200,7 +200,7 @@ Marks the file as being dirty. | Param | Type | Description | | --- | --- | --- | -| changeList | Object | {from: {line:number, ch: number}, to: {line:number, ch:number}} | +| changeList | Object | An object representing the change range with `from` and `to` properties, each containing `line` and `ch` numbers. | diff --git a/docs/API-Reference/command/KeyBindingManager.md b/docs/API-Reference/command/KeyBindingManager.md index 496a644bd5..b4c1fbf0c2 100644 --- a/docs/API-Reference/command/KeyBindingManager.md +++ b/docs/API-Reference/command/KeyBindingManager.md @@ -68,9 +68,10 @@ Remove a key binding from _keymap -## getKeymap([defaults]) ⇒ Object.<string, {commandID: string, key: string, displayKey: string}> +## getKeymap([defaults]) ⇒ Object Returns a copy of the current key map. If the optional 'defaults' parameter is true, then a copy of the default key map is returned. +In the default keymap each key is associated with an object containing `commandID`, `key`, and `displayKey`. **Kind**: global function diff --git a/docs/API-Reference/widgets/Dialogs.md b/docs/API-Reference/widgets/Dialogs.md index d6666941f4..f6f0d00283 100644 --- a/docs/API-Reference/widgets/Dialogs.md +++ b/docs/API-Reference/widgets/Dialogs.md @@ -72,7 +72,7 @@ The template can either be a string or a jQuery object representing a DOM node t -## showModalDialog(dlgClass, [title], [message], [buttons], [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +## showModalDialog(dlgClass, [title], [message], buttons, [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) Creates a new general purpose modal dialog using the default template and the template variables given as parameters as described. @@ -83,7 +83,7 @@ as parameters as described. | dlgClass | string | A class name identifier for the dialog. Typically one of DefaultDialogs.* | | [title] | string | The title of the dialog. Can contain HTML markup. Defaults to "". | | [message] | string | The message to display in the dialog. Can contain HTML markup. Defaults to "". | -| [buttons] | Array.<{className: string, id: string, text: string, tooltip:string}> | An array of buttons where each button has a class, id tooltip, and text property. The id is used in "data-button-id". Defaults to a single Ok button. Typically className is one of DIALOG_BTN_CLASS_*, id is one of DIALOG_BTN_* | +| buttons | Array.<Object> | An array of buttons where each button has a class, id tooltip, and text property. The id is used in "data-button-id". Defaults to a single Ok button. Typically className is one of DIALOG_BTN_CLASS_*, id is one of DIALOG_BTN_* | | [autoDismiss] | boolean | Whether to automatically dismiss the dialog when one of the buttons is clicked. Default true. If false, you'll need to manually handle button clicks and the Esc key, and dismiss the dialog yourself when ready by calling `close()` on the returned dialog. | From 59b786fcbd1f5abcb0780453d3baf47989226fdb Mon Sep 17 00:00:00 2001 From: Pluto Date: Thu, 7 Nov 2024 18:46:39 +0530 Subject: [PATCH 3/6] docs: fix additional build fail issues --- docs/API-Reference/command/KeyBindingManager.md | 10 +++++----- docs/API-Reference/widgets/Dialogs.md | 2 +- src/command/KeyBindingManager.js | 11 ++++++----- src/widgets/Dialogs.js | 2 +- 4 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/API-Reference/command/KeyBindingManager.md b/docs/API-Reference/command/KeyBindingManager.md index b4c1fbf0c2..6a1a42466c 100644 --- a/docs/API-Reference/command/KeyBindingManager.md +++ b/docs/API-Reference/command/KeyBindingManager.md @@ -81,27 +81,27 @@ In the default keymap each key is associated with an object containing `commandI -## addBinding(command, keyBindings, platform, options) ⇒ Object \| Array.<{key: string, displayKey:String}> +## addBinding(command, keyBindings, platform, options) ⇒ Object Add one or more key bindings to a particular Command. +Returns record(s) for valid key binding(s). **Kind**: global function -**Returns**: Object \| Array.<{key: string, displayKey:String}> - Returns record(s) for valid key binding(s) | Param | Type | Description | | --- | --- | --- | | command | string \| Command | A command ID or command object | -| keyBindings | Object \| Array.<{key: string, displayKey: string, platform: string}> | A single key binding or an array of keybindings. Example: "Shift-Cmd-F". Mac and Win key equivalents are automatically mapped to each other. Use displayKey property to display a different string (e.g. "CMD+" instead of "CMD="). | +| keyBindings | Object | A single key binding or an array of keybindings. In an array of keybinding `platform` property is also available. Example: "Shift-Cmd-F". Mac and Win key equivalents are automatically mapped to each other. Use displayKey property to display a different string (e.g. "CMD+" instead of "CMD="). | | platform | string | The target OS of the keyBindings either "mac", "win" or "linux". If undefined, all platforms not explicitly defined will use the key binding. NOTE: If platform is not specified, Ctrl will be replaced by Cmd for "mac" platform | | options | object | | | options.isMenuShortcut | boolean | this allows alt-key shortcuts to be registered. | -## getKeyBindings(command) ⇒ Array.<{{key: string, displayKey: string}}> +## getKeyBindings(command) ⇒ Array.<Object> Retrieve key bindings currently associated with a command **Kind**: global function -**Returns**: Array.<{{key: string, displayKey: string}}> - An array of associated key bindings. +**Returns**: Array.<Object> - The object has two properties `key` and `displayKey` | Param | Type | Description | | --- | --- | --- | diff --git a/docs/API-Reference/widgets/Dialogs.md b/docs/API-Reference/widgets/Dialogs.md index f6f0d00283..65509100a5 100644 --- a/docs/API-Reference/widgets/Dialogs.md +++ b/docs/API-Reference/widgets/Dialogs.md @@ -144,7 +144,7 @@ be called with the special buttonId DIALOG_CANCELED (note: callback is run async ## addLinkTooltips(elementOrDialog) -Ensures that all tags with a URL have a tooltip showing the same URL +Ensures that all anchor tags with a URL have a tooltip showing the same URL **Kind**: global function diff --git a/src/command/KeyBindingManager.js b/src/command/KeyBindingManager.js index a57fd6565a..7d25135cf3 100644 --- a/src/command/KeyBindingManager.js +++ b/src/command/KeyBindingManager.js @@ -980,10 +980,12 @@ define(function (require, exports, module) { /** * Add one or more key bindings to a particular Command. + * Returns record(s) for valid key binding(s). * * @param {!string | Command} command - A command ID or command object - * @param {?({key: string, displayKey: string}|Array.<{key: string, displayKey: string, platform: string}>)} keyBindings - * A single key binding or an array of keybindings. Example: + * @param {{key: string, displayKey:string, platform: string}} keyBindings + * A single key binding or an array of keybindings. + * In an array of keybinding `platform` property is also available. Example: * "Shift-Cmd-F". Mac and Win key equivalents are automatically * mapped to each other. Use displayKey property to display a different * string (e.g. "CMD+" instead of "CMD="). @@ -993,8 +995,7 @@ define(function (require, exports, module) { * NOTE: If platform is not specified, Ctrl will be replaced by Cmd for "mac" platform * @param {object?} options * @param {boolean?} options.isMenuShortcut this allows alt-key shortcuts to be registered. - * @return {{key: string, displayKey:String}|Array.<{key: string, displayKey:String}>} - * Returns record(s) for valid key binding(s) + * @return {{key: string, displayKey:string}} */ function addBinding(command, keyBindings, platform, options={}) { let commandID = "", @@ -1045,7 +1046,7 @@ define(function (require, exports, module) { * Retrieve key bindings currently associated with a command * * @param {!string | Command} command - A command ID or command object - * @return {!Array.<{{key: string, displayKey: string}}>} An array of associated key bindings. + * @return {Array.} The object has two properties `key` and `displayKey` */ function getKeyBindings(command) { let bindings = [], diff --git a/src/widgets/Dialogs.js b/src/widgets/Dialogs.js index 0fd7ea573a..ec868e6b22 100644 --- a/src/widgets/Dialogs.js +++ b/src/widgets/Dialogs.js @@ -552,7 +552,7 @@ define(function (require, exports, module) { }); /** - * Ensures that all tags with a URL have a tooltip showing the same URL + * Ensures that all anchor tags with a URL have a tooltip showing the same URL * @param {!jQueryObject|Dialog} elementOrDialog Dialog intance, or root of other DOM tree to add tooltips to */ function addLinkTooltips(elementOrDialog) { From cde1a6f4660bb024cfb85b143247c18b30d8ab31 Mon Sep 17 00:00:00 2001 From: Pluto Date: Thu, 7 Nov 2024 18:55:20 +0530 Subject: [PATCH 4/6] docs: fix further build fail issues --- docs/API-Reference/command/KeyBindingManager.md | 2 +- src/command/KeyBindingManager.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API-Reference/command/KeyBindingManager.md b/docs/API-Reference/command/KeyBindingManager.md index 6a1a42466c..7361d07062 100644 --- a/docs/API-Reference/command/KeyBindingManager.md +++ b/docs/API-Reference/command/KeyBindingManager.md @@ -180,7 +180,7 @@ under use preset dropdown. For EG. distribute a `netbeans editor` shortcuts pack | --- | --- | --- | | packID | string | A unique ID for the pack. Use `extensionID.name` format to avoid collisions. | | packName | string | A name for the pack. | -| keyMap | Object | a keymap of the format {`Ctrl-Alt-L`: `file.liveFilePreview`} depending on the platform. The extension should decide the correct keymap based on the platform before calling this function. | +| keyMap | Object | a keymap of the format `{'Ctrl-Alt-L': 'file.liveFilePreview'}` depending on the platform. The extension should decide the correct keymap based on the platform before calling this function. | diff --git a/src/command/KeyBindingManager.js b/src/command/KeyBindingManager.js index 7d25135cf3..a80c2b23a9 100644 --- a/src/command/KeyBindingManager.js +++ b/src/command/KeyBindingManager.js @@ -1683,7 +1683,7 @@ define(function (require, exports, module) { * * @param {string} packID - A unique ID for the pack. Use `extensionID.name` format to avoid collisions. * @param {string} packName - A name for the pack. - * @param {Object} keyMap - a keymap of the format {`Ctrl-Alt-L`: `file.liveFilePreview`} depending on the platform. + * @param {Object} keyMap - a keymap of the format `{'Ctrl-Alt-L': 'file.liveFilePreview'}` depending on the platform. * The extension should decide the correct keymap based on the platform before calling this function. */ function registerCustomKeymapPack(packID, packName, keyMap) { From 858fdaa720f6cd67342e8d3bc6aea1b41507da46 Mon Sep 17 00:00:00 2001 From: Pluto Date: Fri, 8 Nov 2024 00:14:28 +0530 Subject: [PATCH 5/6] docs: add required files to API docs --- .../features/PriorityBasedRegistration.md | 5 + .../filesystem/FileSystemError.md | 62 +++++++++ .../filesystem/FileSystemStats.md | 50 +++++++ docs/API-Reference/filesystem/RemoteFile.md | 122 ++++++++++++++++++ docs/API-Reference/filesystem/WatchedRoot.md | 75 +++++++++++ src/features/PriorityBasedRegistration.js | 11 ++ src/filesystem/FileSystemError.js | 38 ++++-- src/filesystem/FileSystemStats.js | 48 ++++++- src/filesystem/RemoteFile.js | 28 +++- src/filesystem/WatchedRoot.js | 24 +++- 10 files changed, 448 insertions(+), 15 deletions(-) create mode 100644 docs/API-Reference/features/PriorityBasedRegistration.md create mode 100644 docs/API-Reference/filesystem/FileSystemError.md create mode 100644 docs/API-Reference/filesystem/FileSystemStats.md create mode 100644 docs/API-Reference/filesystem/RemoteFile.md create mode 100644 docs/API-Reference/filesystem/WatchedRoot.md diff --git a/docs/API-Reference/features/PriorityBasedRegistration.md b/docs/API-Reference/features/PriorityBasedRegistration.md new file mode 100644 index 0000000000..f2845035b9 --- /dev/null +++ b/docs/API-Reference/features/PriorityBasedRegistration.md @@ -0,0 +1,5 @@ +### Import : +```js +const PriorityBasedRegistration = brackets.getModule("features/PriorityBasedRegistration") +``` + diff --git a/docs/API-Reference/filesystem/FileSystemError.md b/docs/API-Reference/filesystem/FileSystemError.md new file mode 100644 index 0000000000..b94623c909 --- /dev/null +++ b/docs/API-Reference/filesystem/FileSystemError.md @@ -0,0 +1,62 @@ +### Import : +```js +const FileSystemError = brackets.getModule("filesystem/FileSystemError") +``` + + + +## FileSystemError FileSystemError + + +FileSystemError describes the errors that can occur when using the FileSystem, File, +and Directory modules. + +Error values are strings. Any falsy value: null, undefined or means no error. + +Enumerated File System Errors +```js + UNKNOWN: Unknown, + INVALID\_PARAMS: InvalidParams, + NOT\_FOUND: NotFound, + NOT\_READABLE: NotReadable, + UNSUPPORTED\_ENCODING: UnsupportedEncoding, + NOT\_SUPPORTED: NotSupported, + NOT\_WRITABLE: NotWritable, + OUT\_OF\_SPACE: OutOfSpace, + TOO\_MANY\_ENTRIES: TooManyEntries, + ALREADY\_EXISTS: AlreadyExists, + CONTENTS\_MODIFIED: ContentsModified, + ROOT\_NOT\_WATCHED: RootNotBeingWatched, + EXCEEDS\_MAX\_FILE\_SIZE: ExceedsMaxFileSize, + NETWORK\_DRIVE\_NOT\_SUPPORTED: NetworkDriveNotSupported, + ENCODE\_FILE\_FAILED: EncodeFileFailed, + DECODE\_FILE\_FAILED: DecodeFileFailed, + UNSUPPORTED\_UTF16\_ENCODING: UnsupportedUTF16Encoding + ``` diff --git a/docs/API-Reference/filesystem/FileSystemStats.md b/docs/API-Reference/filesystem/FileSystemStats.md new file mode 100644 index 0000000000..d7944f0654 --- /dev/null +++ b/docs/API-Reference/filesystem/FileSystemStats.md @@ -0,0 +1,50 @@ +### Import : +```js +const FileSystemStats = brackets.getModule("filesystem/FileSystemStats") +``` + + + +## FileSystemStats +**Kind**: global class + + +### new FileSystemStats(options) +The FileSystemStats represents a particular FileSystemEntry's stats. + + +| Param | Type | +| --- | --- | +| options | Object | + + + +## isFile : boolean +Whether or not this is a stats object for a file + +**Kind**: global variable + + +## isDirectory : boolean +Whether or not this is a stats object for a directory + +**Kind**: global variable + + +## mtime : Date +Modification time for a file + +**Kind**: global variable + + +## size : Number +Size in bytes of a file + +**Kind**: global variable + + +## realPath : string +The canonical path of this file or directory ONLY if it is a symbolic link, +and null otherwise. + +**Kind**: global variable diff --git a/docs/API-Reference/filesystem/RemoteFile.md b/docs/API-Reference/filesystem/RemoteFile.md new file mode 100644 index 0000000000..3f8349225a --- /dev/null +++ b/docs/API-Reference/filesystem/RemoteFile.md @@ -0,0 +1,122 @@ +### Import : +```js +const RemoteFile = brackets.getModule("filesystem/RemoteFile") +``` + + + +## RemoteFile +**Kind**: global class + +* [RemoteFile](#RemoteFile) + * [new RemoteFile(fullPath, fileSystem)](#new_RemoteFile_new) + * [.toString()](#RemoteFile+toString) + * [.stat(callback)](#RemoteFile+stat) + * [.read([options], callback)](#RemoteFile+read) + * [.write(data, [options], [callback])](#RemoteFile+write) + * [.exists(callback)](#RemoteFile+exists) + * [.unlink(callback)](#RemoteFile+unlink) + * [.rename(callback)](#RemoteFile+rename) + * [.moveToTrash(callback)](#RemoteFile+moveToTrash) + + + +### new RemoteFile(fullPath, fileSystem) +Model for a RemoteFile. + +This class should *not* be instantiated directly. Use FileSystem.getFileForPath + +See the FileSystem class for more details. + + +| Param | Type | Description | +| --- | --- | --- | +| fullPath | string | The full path for this File. | +| fileSystem | FileSystem | The file system associated with this File. | + + + +### remoteFile.toString() +Helpful toString for debugging and equality check purposes + +**Kind**: instance method of [RemoteFile](#RemoteFile) + + +### remoteFile.stat(callback) +Returns the stats for the remote entry. + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | Description | +| --- | --- | --- | +| callback | function | Callback with a FileSystemError string or FileSystemStats object. | + + + +### remoteFile.read([options], callback) +Reads a remote file. + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | Description | +| --- | --- | --- | +| [options] | Object | Currently unused. | +| callback | function | Callback that is passed the FileSystemError string or the file's contents and its stats. | + + + +### remoteFile.write(data, [options], [callback]) +Write a file. + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | Description | +| --- | --- | --- | +| data | string | Data to write. | +| [options] | object | Currently unused. | +| [callback] | function | Callback that is passed the FileSystemError string or the file's new stats. | + + + +### remoteFile.exists(callback) +Check if the remote file exists or not + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | +| --- | --- | +| callback | function | + + + +### remoteFile.unlink(callback) +Unlink the remote file + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | +| --- | --- | +| callback | function | + + + +### remoteFile.rename(callback) +Rename the remote file + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | +| --- | --- | +| callback | function | + + + +### remoteFile.moveToTrash(callback) +Move the remote file to trash + +**Kind**: instance method of [RemoteFile](#RemoteFile) + +| Param | Type | +| --- | --- | +| callback | function | + diff --git a/docs/API-Reference/filesystem/WatchedRoot.md b/docs/API-Reference/filesystem/WatchedRoot.md new file mode 100644 index 0000000000..527b92b4b7 --- /dev/null +++ b/docs/API-Reference/filesystem/WatchedRoot.md @@ -0,0 +1,75 @@ +### Import : +```js +const WatchedRoot = brackets.getModule("filesystem/WatchedRoot") +``` + + + +## WatchedRoot +**Kind**: global class + +* [WatchedRoot](#WatchedRoot) + * [new WatchedRoot(entry, filter, filterGitIgnore)](#new_WatchedRoot_new) + * _instance_ + * [.entry](#WatchedRoot+entry) : File \| Directory + * [.filter](#WatchedRoot+filter) : function + * [.filterGitIgnore](#WatchedRoot+filterGitIgnore) : string \| Array.<string> + * [.status](#WatchedRoot+status) : number + * _static_ + * [.INACTIVE](#WatchedRoot.INACTIVE) : number + * [.STARTING](#WatchedRoot.STARTING) : number + * [.ACTIVE](#WatchedRoot.ACTIVE) : number + + + +### new WatchedRoot(entry, filter, filterGitIgnore) +Represents file or directory structure watched by the FileSystem. If the +entry is a directory, all children (that pass the supplied filter function) +are also watched. A WatchedRoot object begins and ends its life in the +INACTIVE state. While in the process of starting up watchers, the WatchedRoot +is in the STARTING state. When watchers are ready, the WatchedRoot enters +the ACTIVE state. + +See the FileSystem class for more details. + + +| Param | Type | +| --- | --- | +| entry | File \| Directory | +| filter | function | +| filterGitIgnore | string \| Array.<string> | + + + +### watchedRoot.entry : File \| Directory +**Kind**: instance property of [WatchedRoot](#WatchedRoot) + + +### watchedRoot.filter : function +**Kind**: instance property of [WatchedRoot](#WatchedRoot) + + +### watchedRoot.filterGitIgnore : string \| Array.<string> +**Kind**: instance property of [WatchedRoot](#WatchedRoot) + + +### watchedRoot.status : number +**Kind**: instance property of [WatchedRoot](#WatchedRoot) + + +### WatchedRoot.INACTIVE : number +WatchedRoot inactive + +**Kind**: static constant of [WatchedRoot](#WatchedRoot) + + +### WatchedRoot.STARTING : number +WatchedRoot starting + +**Kind**: static constant of [WatchedRoot](#WatchedRoot) + + +### WatchedRoot.ACTIVE : number +WatchedRoot active + +**Kind**: static constant of [WatchedRoot](#WatchedRoot) diff --git a/src/features/PriorityBasedRegistration.js b/src/features/PriorityBasedRegistration.js index 1fd7c48c06..be44b44335 100644 --- a/src/features/PriorityBasedRegistration.js +++ b/src/features/PriorityBasedRegistration.js @@ -22,6 +22,9 @@ */ /* eslint-disable indent */ + +// @INCLUDE_IN_API_DOCS + define(function (require, exports, module) { @@ -29,6 +32,7 @@ define(function (require, exports, module) { /** * Comparator to sort providers from high to low priority + * @private */ function _providerSort(a, b) { return b.priority - a.priority; @@ -108,6 +112,13 @@ define(function (require, exports, module) { }; + /** + * Gets the list of providers for a specific language ID, including global providers. + * Filters out providers that are disabled in the preferences. + * + * @param {string} languageId language ID for which to get the providers + * @return {Array.} sorted list of active providers for given language + */ RegistrationHandler.prototype.getProvidersForLanguageId = function (languageId) { var providers = (this._providers[languageId] || []).concat(this._providers.all || []) .sort(_providerSort); diff --git a/src/filesystem/FileSystemError.js b/src/filesystem/FileSystemError.js index d59ba9f78e..b87e31190b 100644 --- a/src/filesystem/FileSystemError.js +++ b/src/filesystem/FileSystemError.js @@ -19,19 +19,39 @@ * */ -/** - * FileSystemError describes the errors that can occur when using the FileSystem, File, - * and Directory modules. - * - * Error values are strings. Any "falsy" value: null, undefined or "" means "no error". - */ -define(function (require, exports, module) { +// @INCLUDE_IN_API_DOCS +define(function (require, exports, module) { /** + * @module FileSystemError FileSystemError + * + * + * FileSystemError describes the errors that can occur when using the FileSystem, File, + * and Directory modules. + * + * Error values are strings. Any "falsy" value: null, undefined or "" means "no error". + * * Enumerated File System Errors - * @module - * @enum {string} + * ```js + * UNKNOWN: "Unknown", + * INVALID_PARAMS: "InvalidParams", + * NOT_FOUND: "NotFound", + * NOT_READABLE: "NotReadable", + * UNSUPPORTED_ENCODING: "UnsupportedEncoding", + * NOT_SUPPORTED: "NotSupported", + * NOT_WRITABLE: "NotWritable", + * OUT_OF_SPACE: "OutOfSpace", + * TOO_MANY_ENTRIES: "TooManyEntries", + * ALREADY_EXISTS: "AlreadyExists", + * CONTENTS_MODIFIED: "ContentsModified", + * ROOT_NOT_WATCHED: "RootNotBeingWatched", + * EXCEEDS_MAX_FILE_SIZE: "ExceedsMaxFileSize", + * NETWORK_DRIVE_NOT_SUPPORTED: "NetworkDriveNotSupported", + * ENCODE_FILE_FAILED: "EncodeFileFailed", + * DECODE_FILE_FAILED: "DecodeFileFailed", + * UNSUPPORTED_UTF16_ENCODING: "UnsupportedUTF16Encoding" + * ``` */ module.exports = { UNKNOWN: "Unknown", diff --git a/src/filesystem/FileSystemStats.js b/src/filesystem/FileSystemStats.js index ac0e8536f3..315c4272dc 100644 --- a/src/filesystem/FileSystemStats.js +++ b/src/filesystem/FileSystemStats.js @@ -19,13 +19,12 @@ * */ -/** - * The FileSystemStats represents a particular FileSystemEntry's stats. - */ -define(function (require, exports, module) { +// @INCLUDE_IN_API_DOCS +define(function (require, exports, module) { /** + * The FileSystemStats represents a particular FileSystemEntry's stats. * @constructor * @param {{isFile: boolean, mtime: Date, size: Number, realPath: ?string, hash: object}} options */ @@ -54,22 +53,52 @@ define(function (require, exports, module) { // Add "isFile", "isDirectory", "mtime" and "size" getters Object.defineProperties(FileSystemStats.prototype, { + /** + * Whether or not this is a stats object for a file + * + * @type {boolean} + */ "isFile": { get: function () { return this._isFile; }, set: function () { throw new Error("Cannot set isFile"); } }, + + /** + * Whether or not this is a stats object for a directory + * + * @type {boolean} + */ "isDirectory": { get: function () { return this._isDirectory; }, set: function () { throw new Error("Cannot set isDirectory"); } }, + + /** + * Modification time for a file + * + * @type {Date} + */ "mtime": { get: function () { return this._mtime; }, set: function () { throw new Error("Cannot set mtime"); } }, + + /** + * Size in bytes of a file + * + * @type {Number} + */ "size": { get: function () { return this._size; }, set: function () { throw new Error("Cannot set size"); } }, + + /** + * The canonical path of this file or directory ONLY if it is a symbolic link, + * and null otherwise. + * + * @type {?string} + */ "realPath": { get: function () { return this._realPath; }, set: function () { throw new Error("Cannot set realPath"); } @@ -78,30 +107,40 @@ define(function (require, exports, module) { /** * Whether or not this is a stats object for a file + * + * @private * @type {boolean} */ FileSystemStats.prototype._isFile = false; /** * Whether or not this is a stats object for a directory + * + * @private * @type {boolean} */ FileSystemStats.prototype._isDirectory = false; /** * Modification time for a file + * + * @private * @type {Date} */ FileSystemStats.prototype._mtime = null; /** * Size in bytes of a file + * + * @private * @type {Number} */ FileSystemStats.prototype._size = null; /** * Consistency hash for a file + * + * @private * @type {object} */ FileSystemStats.prototype._hash = null; @@ -110,6 +149,7 @@ define(function (require, exports, module) { * The canonical path of this file or directory ONLY if it is a symbolic link, * and null otherwise. * + * @private * @type {?string} */ FileSystemStats.prototype._realPath = null; diff --git a/src/filesystem/RemoteFile.js b/src/filesystem/RemoteFile.js index bc1039e64d..5de35874bd 100644 --- a/src/filesystem/RemoteFile.js +++ b/src/filesystem/RemoteFile.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + define(function (require, exports, module) { @@ -31,7 +33,8 @@ define(function (require, exports, module) { /** * Create a new file stat. See the FileSystemStats class for more details. * - * @param {!string} fullPath The full path for this File. + * @private + * @param {!string} uri The full path for this File. * @return {FileSystemStats} stats. */ function _getStats(uri) { @@ -137,6 +140,7 @@ define(function (require, exports, module) { /** * Cached contents of this file. This value is nullable but should NOT be undefined. + * * @private * @type {?string} */ @@ -159,6 +163,7 @@ define(function (require, exports, module) { /** * Clear any cached data for this file. Note that this explicitly does NOT * clear the file's hash. + * * @private */ RemoteFile.prototype._clearCachedData = function () { @@ -254,18 +259,39 @@ define(function (require, exports, module) { callback(FileSystemError.NOT_FOUND); }; + /** + * Check if the remote file exists or not + * + * @param {function (err?, ?string, string=, FileSystemStats=)} callback + */ RemoteFile.prototype.exists = function (callback) { callback(null, true); }; + /** + * Unlink the remote file + * + * @param {function (err?, ?string, string=, FileSystemStats=)} callback + */ RemoteFile.prototype.unlink = function (callback) { callback(FileSystemError.NOT_FOUND); }; + + /** + * Rename the remote file + * + * @param {function (err?, ?string, string=, FileSystemStats=)} callback + */ RemoteFile.prototype.rename = function (newName, callback) { callback(FileSystemError.NOT_FOUND); }; + /** + * Move the remote file to trash + * + * @param {function (err?, ?string, string=, FileSystemStats=)} callback + */ RemoteFile.prototype.moveToTrash = function (callback) { callback(FileSystemError.NOT_FOUND); }; diff --git a/src/filesystem/WatchedRoot.js b/src/filesystem/WatchedRoot.js index ea5c45eaa8..b94bf271b0 100644 --- a/src/filesystem/WatchedRoot.js +++ b/src/filesystem/WatchedRoot.js @@ -19,10 +19,12 @@ * */ +// @INCLUDE_IN_API_DOCS + define(function (require, exports, module) { - /* + /** * Represents file or directory structure watched by the FileSystem. If the * entry is a directory, all children (that pass the supplied filter function) * are also watched. A WatchedRoot object begins and ends its life in the @@ -44,8 +46,28 @@ define(function (require, exports, module) { } // Status constants + /** + * WatchedRoot inactive + * + * @const + * @type {number} + */ WatchedRoot.INACTIVE = 0; + + /** + * WatchedRoot starting + * + * @const + * @type {number} + */ WatchedRoot.STARTING = 1; + + /** + * WatchedRoot active + * + * @const + * @type {number} + */ WatchedRoot.ACTIVE = 2; /** From 7fcacd66109c94d06a9e693d07d9a93784bf8fe6 Mon Sep 17 00:00:00 2001 From: Pluto Date: Fri, 8 Nov 2024 00:49:03 +0530 Subject: [PATCH 6/6] docs: fix jsdoc issues with module tag --- .../filesystem/FileSystemError.md | 69 ++++++------------- src/filesystem/FileSystemError.js | 4 +- 2 files changed, 24 insertions(+), 49 deletions(-) diff --git a/docs/API-Reference/filesystem/FileSystemError.md b/docs/API-Reference/filesystem/FileSystemError.md index b94623c909..ced64af40f 100644 --- a/docs/API-Reference/filesystem/FileSystemError.md +++ b/docs/API-Reference/filesystem/FileSystemError.md @@ -3,60 +3,33 @@ const FileSystemError = brackets.getModule("filesystem/FileSystemError") ``` - +## FileSystemError FileSystemError describes the errors that can occur when using the FileSystem, File, and Directory modules. -Error values are strings. Any falsy value_ null, undefined or means no error. +Error values are strings. Any "falsy" value: null, undefined or "" means "no error". Enumerated File System Errors -```js - UNKNOWN_ Unknown, - INVALID_PARAMS_ InvalidParams, - NOT_FOUND_ NotFound, - NOT_READABLE_ NotReadable, - UNSUPPORTED_ENCODING_ UnsupportedEncoding, - NOT_SUPPORTED_ NotSupported, - NOT_WRITABLE_ NotWritable, - OUT_OF_SPACE_ OutOfSpace, - TOO_MANY_ENTRIES_ TooManyEntries, - ALREADY_EXISTS_ AlreadyExists, - CONTENTS_MODIFIED_ ContentsModified, - ROOT_NOT_WATCHED_ RootNotBeingWatched, - EXCEEDS_MAX_FILE_SIZE_ ExceedsMaxFileSize, - NETWORK_DRIVE_NOT_SUPPORTED_ NetworkDriveNotSupported, - ENCODE_FILE_FAILED_ EncodeFileFailed, - DECODE_FILE_FAILED_ DecodeFileFailed, - UNSUPPORTED_UTF16_ENCODING_ UnsupportedUTF16Encoding - ```module_"> - -## FileSystemError FileSystemError - - -FileSystemError describes the errors that can occur when using the FileSystem, File, -and Directory modules. - -Error values are strings. Any falsy value: null, undefined or means no error. -Enumerated File System Errors ```js - UNKNOWN: Unknown, - INVALID\_PARAMS: InvalidParams, - NOT\_FOUND: NotFound, - NOT\_READABLE: NotReadable, - UNSUPPORTED\_ENCODING: UnsupportedEncoding, - NOT\_SUPPORTED: NotSupported, - NOT\_WRITABLE: NotWritable, - OUT\_OF\_SPACE: OutOfSpace, - TOO\_MANY\_ENTRIES: TooManyEntries, - ALREADY\_EXISTS: AlreadyExists, - CONTENTS\_MODIFIED: ContentsModified, - ROOT\_NOT\_WATCHED: RootNotBeingWatched, - EXCEEDS\_MAX\_FILE\_SIZE: ExceedsMaxFileSize, - NETWORK\_DRIVE\_NOT\_SUPPORTED: NetworkDriveNotSupported, - ENCODE\_FILE\_FAILED: EncodeFileFailed, - DECODE\_FILE\_FAILED: DecodeFileFailed, - UNSUPPORTED\_UTF16\_ENCODING: UnsupportedUTF16Encoding + UNKNOWN: "Unknown", + INVALID_PARAMS: "InvalidParams", + NOT_FOUND: "NotFound", + NOT_READABLE: "NotReadable", + UNSUPPORTED_ENCODING: "UnsupportedEncoding", + NOT_SUPPORTED: "NotSupported", + NOT_WRITABLE: "NotWritable", + OUT_OF_SPACE: "OutOfSpace", + TOO_MANY_ENTRIES: "TooManyEntries", + ALREADY_EXISTS: "AlreadyExists", + CONTENTS_MODIFIED: "ContentsModified", + ROOT_NOT_WATCHED: "RootNotBeingWatched", + EXCEEDS_MAX_FILE_SIZE: "ExceedsMaxFileSize", + NETWORK_DRIVE_NOT_SUPPORTED: "NetworkDriveNotSupported", + ENCODE_FILE_FAILED: "EncodeFileFailed", + DECODE_FILE_FAILED: "DecodeFileFailed", + UNSUPPORTED_UTF16_ENCODING: "UnsupportedUTF16Encoding" ``` + diff --git a/src/filesystem/FileSystemError.js b/src/filesystem/FileSystemError.js index b87e31190b..49bbcfc970 100644 --- a/src/filesystem/FileSystemError.js +++ b/src/filesystem/FileSystemError.js @@ -24,7 +24,6 @@ define(function (require, exports, module) { /** - * @module FileSystemError FileSystemError * * * FileSystemError describes the errors that can occur when using the FileSystem, File, @@ -33,6 +32,7 @@ define(function (require, exports, module) { * Error values are strings. Any "falsy" value: null, undefined or "" means "no error". * * Enumerated File System Errors + * * ```js * UNKNOWN: "Unknown", * INVALID_PARAMS: "InvalidParams", @@ -52,6 +52,8 @@ define(function (require, exports, module) { * DECODE_FILE_FAILED: "DecodeFileFailed", * UNSUPPORTED_UTF16_ENCODING: "UnsupportedUTF16Encoding" * ``` + * + * @module FileSystemError */ module.exports = { UNKNOWN: "Unknown",