docs: refine API docs for files in Command dir

phcode-dev · Oct 25, 2024 · a73b23f · a73b23f
1 parent 384bf71
commit a73b23f
Show file tree

Hide file tree

Showing 6 changed files with 142 additions and 130 deletions.
diff --git a/docs/API-Reference/command/CommandManager.md b/docs/API-Reference/command/CommandManager.md
@@ -3,34 +3,39 @@
 const CommandManager = brackets.getModule("command/CommandManager")
 ```
 
-<a name="_commands"></a>
+<a name="EventDispatcher"></a>
 
-## \_commands : <code>Object</code>
-Map of all registered global commands
+## EventDispatcher
+Manages global application commands that can be called from menu items, key bindings, or subparts
+of the application.
 
-**Kind**: global variable  
-**Properties**
+This module dispatches these event(s):
+   - commandRegistered  -- when a new command is registered
+   - beforeExecuteCommand -- before dispatching a command
 
-| Name | Type | Description |
-| --- | --- | --- |
-| commands | <code>Object.&lt;string, Command&gt;</code> | A map of command IDs to Command objects. |
+**Kind**: global constant  
+<a name="EVENT_BEFORE_EXECUTE_COMMAND"></a>
 
-<a name="_commandsOriginal"></a>
+## EVENT\_BEFORE\_EXECUTE\_COMMAND : <code>string</code>
+Event triggered before command executes.
 
-## \_commandsOriginal : <code>Object</code>
-Temporary copy of commands map for restoring after testingTODO (issue #1039): implement separate require contexts for unit tests
+**Kind**: global constant  
+<a name="SOURCE_KEYBOARD_SHORTCUT"></a>
 
-**Kind**: global variable  
-**Properties**
+## SOURCE\_KEYBOARD\_SHORTCUT : <code>string</code>
+Keyboard shortcut trigger.
 
-| Name | Type | Description |
-| --- | --- | --- |
-| commands | <code>Object.&lt;string, Command&gt;</code> | A map of command IDs to Command objects. |
+**Kind**: global constant  
+<a name="SOURCE_UI_MENU_CLICK"></a>
 
-<a name="EventDispatcher"></a>
+## SOURCE\_UI\_MENU\_CLICK : <code>string</code>
+UI menu click trigger.
 
-## EventDispatcher
-Manages global application commands that can be called from menu items, key bindings, or subpartsof the application.This module dispatches these event(s):   - commandRegistered  -- when a new command is registered   - beforeExecuteCommand -- before dispatching a command
+**Kind**: global constant  
+<a name="SOURCE_OTHER"></a>
+
+## SOURCE\_OTHER : <code>string</code>
+Other trigger types.
 
 **Kind**: global constant  
 <a name="register"></a>
@@ -60,18 +65,6 @@ Registers a global internal only command.
 | id | <code>string</code> | unique identifier for command.      Core commands in Brackets use a simple command title as an id, for example "app.abort_quit".      Extensions should use the following format: "author.myextension.mycommandname".      For example, "lschmitt.csswizard.format.css". |
 | commandFn | <code>function</code> | the function to call when the command is executed. Any arguments passed to     execute() (after the id) are passed as arguments to the function. If the function is asynchronous,     it must return a jQuery promise that is resolved when the command completes. Otherwise, the     CommandManager will assume it is synchronous, and return a promise that is already resolved. |
 
-<a name="_testReset"></a>
-
-## \_testReset()
-Clear all commands for unit testing, but first make copy of commands so thatthey can be restored afterward
-
-**Kind**: global function  
-<a name="_testRestore"></a>
-
-## \_testRestore()
-Restore original commands after test and release copy
-
-**Kind**: global function  
 <a name="get"></a>
 
 ## get(id) ⇒ [<code>Command</code>](#new_Command_new)

diff --git a/docs/API-Reference/command/DefaultMenus.md b/docs/API-Reference/command/DefaultMenus.md
diff --git a/docs/API-Reference/command/Menus.md b/docs/API-Reference/command/Menus.md
@@ -434,29 +434,29 @@ Menu sections are denoted by dividers or the beginning/end of a menu
 
 | Name | Type | Default |
 | --- | --- | --- |
-| FILE_OPEN_CLOSE_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FILE_SAVE_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FILE_LIVE | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FILE_SETTINGS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FILE_EXTENSION_MANAGER | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_UNDO_REDO_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_TEXT_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_SELECTION_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_MODIFY_SELECTION | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_COMMENT_SELECTION | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_CODE_HINTS_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| EDIT_TOGGLE_OPTIONS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FIND_FIND_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FIND_FIND_IN_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| FIND_REPLACE_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| VIEW_HIDESHOW_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| VIEW_FONTSIZE_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| VIEW_TOGGLE_OPTIONS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| NAVIGATE_GOTO_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| NAVIGATE_DOCUMENTS_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| NAVIGATE_OS_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| NAVIGATE_QUICK_EDIT_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
-| NAVIGATE_QUICK_DOCS_COMMANDS | <code>string</code> | <code>&quot;{\&quot;sectionMarker\&quot;:\&quot;\&quot;}&quot;</code> | 
+| FILE_OPEN_CLOSE_COMMANDS | <code>string</code> | <code>&quot;FILE_OPEN_CLOSE_COMMANDS&quot;</code> | 
+| FILE_SAVE_COMMANDS | <code>string</code> | <code>&quot;FILE_SAVE_COMMANDS&quot;</code> | 
+| FILE_LIVE | <code>string</code> | <code>&quot;FILE_LIVE&quot;</code> | 
+| FILE_SETTINGS | <code>string</code> | <code>&quot;FILE_SETTINGS&quot;</code> | 
+| FILE_EXTENSION_MANAGER | <code>string</code> | <code>&quot;FILE_EXTENSION_MANAGER&quot;</code> | 
+| EDIT_UNDO_REDO_COMMANDS | <code>string</code> | <code>&quot;EDIT_UNDO_REDO_COMMANDS&quot;</code> | 
+| EDIT_TEXT_COMMANDS | <code>string</code> | <code>&quot;EDIT_TEXT_COMMANDS&quot;</code> | 
+| EDIT_SELECTION_COMMANDS | <code>string</code> | <code>&quot;EDIT_SELECTION_COMMANDS&quot;</code> | 
+| EDIT_MODIFY_SELECTION | <code>string</code> | <code>&quot;EDIT_MODIFY_SELECTION&quot;</code> | 
+| EDIT_COMMENT_SELECTION | <code>string</code> | <code>&quot;EDIT_COMMENT_SELECTION&quot;</code> | 
+| EDIT_CODE_HINTS_COMMANDS | <code>string</code> | <code>&quot;EDIT_CODE_HINTS_COMMANDS&quot;</code> | 
+| EDIT_TOGGLE_OPTIONS | <code>string</code> | <code>&quot;EDIT_TOGGLE_OPTIONS&quot;</code> | 
+| FIND_FIND_COMMANDS | <code>string</code> | <code>&quot;FIND_FIND_COMMANDS&quot;</code> | 
+| FIND_FIND_IN_COMMANDS | <code>string</code> | <code>&quot;FIND_FIND_IN_COMMANDS&quot;</code> | 
+| FIND_REPLACE_COMMANDS | <code>string</code> | <code>&quot;FIND_REPLACE_COMMANDS&quot;</code> | 
+| VIEW_HIDESHOW_COMMANDS | <code>string</code> | <code>&quot;VIEW_HIDESHOW_COMMANDS&quot;</code> | 
+| VIEW_FONTSIZE_COMMANDS | <code>string</code> | <code>&quot;VIEW_FONTSIZE_COMMANDS&quot;</code> | 
+| VIEW_TOGGLE_OPTIONS | <code>string</code> | <code>&quot;VIEW_TOGGLE_OPTIONS&quot;</code> | 
+| NAVIGATE_GOTO_COMMANDS | <code>string</code> | <code>&quot;NAVIGATE_GOTO_COMMANDS&quot;</code> | 
+| NAVIGATE_DOCUMENTS_COMMANDS | <code>string</code> | <code>&quot;NAVIGATE_DOCUMENTS_COMMANDS&quot;</code> | 
+| NAVIGATE_OS_COMMANDS | <code>string</code> | <code>&quot;NAVIGATE_OS_COMMANDS&quot;</code> | 
+| NAVIGATE_QUICK_EDIT_COMMANDS | <code>string</code> | <code>&quot;NAVIGATE_QUICK_EDIT_COMMANDS&quot;</code> | 
+| NAVIGATE_QUICK_DOCS_COMMANDS | <code>string</code> | <code>&quot;NAVIGATE_QUICK_DOCS_COMMANDS&quot;</code> | 
 
 <a name="BEFORE"></a>
 
@@ -500,17 +500,6 @@ Retrieves the ContextMenu object for the corresponding id.
 | --- | --- |
 | id | <code>string</code> | 
 
-<a name="removeMenuItemEventListeners"></a>
-
-## removeMenuItemEventListeners(menuItem)
-Removes the attached event listeners from the corresponding object.
-
-**Kind**: global function  
-
-| Param | Type |
-| --- | --- |
-| menuItem | [<code>MenuItem</code>](#MenuItem) | 
-
 <a name="getMenuItem"></a>
 
 ## getMenuItem(id) ⇒ [<code>MenuItem</code>](#MenuItem)

diff --git a/src/command/CommandManager.js b/src/command/CommandManager.js
@@ -34,16 +34,36 @@ define(function (require, exports, module) {
 
     const EventDispatcher = require("utils/EventDispatcher");
 
+    /**
+     * Event triggered before command executes.
+     * @constant {string}
+     */
     const EVENT_BEFORE_EXECUTE_COMMAND = "beforeExecuteCommand";
-    const SOURCE_KEYBOARD_SHORTCUT = "keyboardShortcut",
-        SOURCE_UI_MENU_CLICK = "uiMenuClick",
-        SOURCE_OTHER = "otherExecAction";
+
+    /**
+     * Keyboard shortcut trigger.
+     * @constant {string}
+     */
+    const SOURCE_KEYBOARD_SHORTCUT = "keyboardShortcut";
+
+    /**
+     * UI menu click trigger.
+     * @constant {string}
+     */
+    const SOURCE_UI_MENU_CLICK = "uiMenuClick";
+
+    /**
+     * Other trigger types.
+     * @constant {string}
+     */
+    const SOURCE_OTHER = "otherExecAction";
 
 
     /**
      * Map of all registered global commands
      * @type {Object} CommandMap
      * @property {Object.<string, Command>} commands - A map of command IDs to Command objects.
+     * @private
      */
     let _commands = {};
 
@@ -52,6 +72,7 @@ define(function (require, exports, module) {
      * TODO (issue #1039): implement separate require contexts for unit tests
      * @type {Object} CommandMap
      * @property {Object.<string, Command>} commands - A map of command IDs to Command objects.
+     * @private
      */
     let _commandsOriginal = {};
 
@@ -83,6 +104,7 @@ define(function (require, exports, module) {
 
     /**
      * Get command id
+     * @private
      * @return {string}
      */
     Command.prototype.getID = function () {
@@ -91,7 +113,7 @@ define(function (require, exports, module) {
 
     /**
      * Executes the command. Additional arguments are passed to the executing function
-     *
+     * @private
      * @return {$.Promise} a jQuery promise that will be resolved when the command completes.
      */
     Command.prototype.execute = function () {
@@ -120,6 +142,7 @@ define(function (require, exports, module) {
 
     /**
      * Is command enabled?
+     * @private
      * @return {boolean}
      */
     Command.prototype.getEnabled = function () {
@@ -129,6 +152,7 @@ define(function (require, exports, module) {
     /**
      * Sets enabled state of Command and dispatches "enabledStateChange"
      * when the enabled state changes.
+     * @private
      * @param {boolean} enabled
      */
     Command.prototype.setEnabled = function (enabled) {
@@ -143,6 +167,7 @@ define(function (require, exports, module) {
     /**
      * Sets enabled state of Command and dispatches "checkedStateChange"
      * when the enabled state changes.
+     * @private
      * @param {boolean} checked
      */
     Command.prototype.setChecked = function (checked) {
@@ -156,6 +181,7 @@ define(function (require, exports, module) {
 
     /**
      * Is command checked?
+     * @private
      * @return {boolean}
      */
     Command.prototype.getChecked = function () {
@@ -169,7 +195,7 @@ define(function (require, exports, module) {
      * Note, a Command name can appear in either HTML or native UI
      * so HTML tags should not be used. To add a Unicode character,
      * use \uXXXX instead of an HTML entity.
-     *
+     * @private
      * @param {string} name
      */
     Command.prototype.setName = function (name) {
@@ -183,6 +209,7 @@ define(function (require, exports, module) {
 
     /**
      * Get command name
+     * @private
      * @return {string}
      */
     Command.prototype.getName = function () {
@@ -259,6 +286,7 @@ define(function (require, exports, module) {
     /**
      * Clear all commands for unit testing, but first make copy of commands so that
      * they can be restored afterward
+     * @private
      */
     function _testReset() {
         _commandsOriginal = _commands;
@@ -267,6 +295,7 @@ define(function (require, exports, module) {
 
     /**
      * Restore original commands after test and release copy
+     * @private
      */
     function _testRestore() {
         _commands = _commandsOriginal;

diff --git a/src/command/DefaultMenus.js b/src/command/DefaultMenus.js
@@ -21,8 +21,6 @@
 
 /*global Phoenix*/
 
-// @INCLUDE_IN_API_DOCS
-
 /**
  * Initializes the default brackets menu items.
  */
-Original file line number
+Diff line change
@@ Expand Up / @@ -21,8 +21,6 @@ @@
     /*global Phoenix*/
-    // @INCLUDE_IN_API_DOCS
     /**
      * Initializes the default brackets menu items.
      */
@@ Expand Down @@