feat: prepare all required files for API docs

Author: devvaannsh

src/JSUtils/Preferences.js

@@ -19,6 +19,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 /**
 
     This class parses configuration values from a JSON object. The expected

src/JSUtils/ScopeManager.js

@@ -19,6 +19,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 /*global Phoenix*/
 
 /*

src/JSUtils/Session.js

@@ -19,19 +19,22 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
+
 /*jslint regexp: true */
 
 define(function (require, exports, module) {
 
 
-    var StringMatch     = require("utils/StringMatch"),
-        TokenUtils      = require("utils/TokenUtils"),
+    var StringMatch = require("utils/StringMatch"),
+        TokenUtils = require("utils/TokenUtils"),
         LanguageManager = require("language/LanguageManager"),
-        HTMLUtils       = require("language/HTMLUtils"),
-        HintUtils       = require("JSUtils/HintUtils"),
-        ScopeManager    = require("JSUtils/ScopeManager"),
-        Acorn           = require("thirdparty/acorn/dist/acorn"),
-        Acorn_Loose     = require("thirdparty/acorn/dist/acorn_loose");
+        HTMLUtils = require("language/HTMLUtils"),
+        HintUtils = require("JSUtils/HintUtils"),
+        ScopeManager = require("JSUtils/ScopeManager"),
+        Acorn = require("thirdparty/acorn/dist/acorn"),
+        Acorn_Loose = require("thirdparty/acorn/dist/acorn_loose");
 
     /**
      * Session objects encapsulate state associated with a hinting session
@@ -159,8 +162,8 @@ define(function (require, exports, module) {
      *      none exists.
      */
     Session.prototype.getNextCursorOnLine = function (cursor) {
-        var doc     = this.editor.document,
-            line    = doc.getLine(cursor.line);
+        var doc = this.editor.document,
+            line = doc.getLine(cursor.line);
 
         if (cursor.ch < line.length) {
             return {
@@ -181,9 +184,9 @@ define(function (require, exports, module) {
      *      cursor position
      */
     Session.prototype._getPreviousToken = function (cursor) {
-        var token   = this.getToken(cursor),
-            prev    = token,
-            doc     = this.editor.document;
+        var token = this.getToken(cursor),
+            prev = token,
+            doc = this.editor.document;
 
         do {
             if (prev.start < cursor.ch) {
@@ -212,9 +215,9 @@ define(function (require, exports, module) {
      *      cursor position
      */
     Session.prototype.getNextToken = function (cursor, skipWhitespace) {
-        var token   = this.getToken(cursor),
-            next    = token,
-            doc     = this.editor.document;
+        var token = this.getToken(cursor),
+            next = token,
+            doc = this.editor.document;
 
         do {
             if (next.end > cursor.ch) {
@@ -242,11 +245,11 @@ define(function (require, exports, module) {
      * @return {string} - the query string for the current cursor position
      */
     Session.prototype.getQuery = function () {
-        var cursor  = this.getCursor(),
-            token   = this.getToken(cursor),
-            query   = "",
-            start   = cursor.ch,
-            end     = start;
+        var cursor = this.getCursor(),
+            token = this.getToken(cursor),
+            query = "",
+            start = cursor.ch,
+            end = start;
 
         if (token) {
             var line = this.getLine(cursor.line);
@@ -309,8 +312,8 @@ define(function (require, exports, module) {
         if (token && token.string === ".") {
             return cursor;
         }
-            // If something has been typed like 'foo.b' then we have to look back 2 tokens
-            // to get past the 'b' token
+        // If something has been typed like 'foo.b' then we have to look back 2 tokens
+        // to get past the 'b' token
         token = this._getPreviousToken(cursor);
         if (token && token.string === ".") {
             return cursor;
@@ -346,10 +349,10 @@ define(function (require, exports, module) {
      * is true, otherwise undefined.
      */
     Session.prototype.getFunctionInfo = function () {
-        var inFunctionCall   = false,
-            cursor           = this.getCursor(),
+        var inFunctionCall = false,
+            cursor = this.getCursor(),
             functionCallPos,
-            token            = this.getToken(cursor),
+            token = this.getToken(cursor),
             lexical,
             self = this,
             foundCall = false;
@@ -365,7 +368,7 @@ define(function (require, exports, module) {
             var type = token.type,
                 nextToken,
                 localLexical,
-                localCursor = {line: cursor.line, ch: token.end};
+                localCursor = { line: cursor.line, ch: token.end };
 
             if (type === "variable-2" || type === "variable" || type === "property") {
                 nextToken = self.getNextToken(localCursor, true);
@@ -435,7 +438,7 @@ define(function (require, exports, module) {
 
                 if (found) {
                     inFunctionCall = true;
-                    functionCallPos = {line: line, ch: col};
+                    functionCallPos = { line: line, ch: col };
                 }
             }
         }
@@ -459,10 +462,10 @@ define(function (require, exports, module) {
      *      always null for non-property lookups.
      */
     Session.prototype.getType = function () {
-        var propertyLookup   = false,
-            context          = null,
-            cursor           = this.getCursor(),
-            token            = this.getToken(cursor);
+        var propertyLookup = false,
+            context = null,
+            cursor = this.getCursor(),
+            token = this.getToken(cursor);
 
         if (token) {
             if (token.type === "property") {
@@ -504,14 +507,14 @@ define(function (require, exports, module) {
     }
 
     /**
-     * Get a list of hints for the current session using the current scope
+     * Retrieves a list of hints for the current session based on the current scope
      * information.
      *
-     * @param {string} query - the query prefix
-     * @param {StringMatcher} matcher - the class to find query matches and sort the results
-     * @return {hints: Array.<string>, needGuesses: boolean} - array of
-     * matching hints. If needGuesses is true, then the caller needs to
-     * request guesses and call getHints again.
+     * @param {string} query - The query prefix used to filter hints.
+     * @param {StringMatcher} matcher - The class used to find query matches and sort the results.
+     * @return {{hints: Array<string>, needGuesses: boolean}} An object containing:
+     *   - `hints`: An array of matching hints.
+     *   - `needGuesses`: A boolean indicating whether the caller needs to request guesses and call getHints again.
      */
     Session.prototype.getHints = function (query, matcher) {
 
@@ -520,9 +523,9 @@ define(function (require, exports, module) {
         }
 
         var MAX_DISPLAYED_HINTS = 500,
-            type                = this.getType(),
-            builtins            = this._getBuiltins(),
-            needGuesses         = false,
+            type = this.getType(),
+            builtins = this._getBuiltins(),
+            needGuesses = false,
             hints;
 
         /**
@@ -573,7 +576,7 @@ define(function (require, exports, module) {
                     }
 
                     if (!type.property && !type.showFunctionType && hint.origin &&
-                            isBuiltin(hint.origin)) {
+                        isBuiltin(hint.origin)) {
                         searchResult.builtin = 1;
                     } else {
                         searchResult.builtin = 0;
@@ -599,20 +602,20 @@ define(function (require, exports, module) {
                 }
             }
 
-            StringMatch.multiFieldSort(hints, [ "matchGoodness", penalizeUnderscoreValueCompare ]);
+            StringMatch.multiFieldSort(hints, ["matchGoodness", penalizeUnderscoreValueCompare]);
         } else {     // identifiers, literals, and keywords
             hints = this.ternHints || [];
             hints = hints.concat(HintUtils.LITERALS);
             hints = hints.concat(HintUtils.KEYWORDS);
             hints = filterWithQueryAndMatcher(hints, matcher);
-            StringMatch.multiFieldSort(hints, [ "matchGoodness", "depth", "builtin", penalizeUnderscoreValueCompare ]);
+            StringMatch.multiFieldSort(hints, ["matchGoodness", "depth", "builtin", penalizeUnderscoreValueCompare]);
         }
 
         if (hints.length > MAX_DISPLAYED_HINTS) {
             hints = hints.slice(0, MAX_DISPLAYED_HINTS);
         }
 
-        return {hints: hints, needGuesses: needGuesses};
+        return { hints: hints, needGuesses: needGuesses };
     };
 
     Session.prototype.setTernHints = function (newHints) {
@@ -656,9 +659,9 @@ define(function (require, exports, module) {
         var fnHint = this.fnType,
             cursor = this.getCursor(),
             token = this.getToken(this.functionCallPos),
-            start = {line: this.functionCallPos.line, ch: token.start},
+            start = { line: this.functionCallPos.line, ch: token.start },
             fragment = this.editor.document.getRange(start,
-                {line: this.functionCallPos.line + 10, ch: 0});
+                { line: this.functionCallPos.line + 10, ch: 0 });
 
         var ast;
         try {
@@ -737,7 +740,7 @@ define(function (require, exports, module) {
             }
         }
 
-        return {parameters: fnHint, currentIndex: currentArg};
+        return { parameters: fnHint, currentIndex: currentArg };
     };
 
     /**
@@ -763,7 +766,7 @@ define(function (require, exports, module) {
             // Alternatively we could strip the non-javascript text, and modify the offset,
             // and/or cursor, but then we have to remember how to reverse the translation
             // to support jump-to-definition
-            var htmlStart = {line: 0, ch: 0};
+            var htmlStart = { line: 0, ch: 0 };
             scriptBlocks.forEach(function (scriptBlock) {
                 var start = scriptBlock.start,
                     end = scriptBlock.end;
@@ -778,7 +781,7 @@ define(function (require, exports, module) {
 
             return text;
         }
-            // Javascript file, just return the text
+        // Javascript file, just return the text
         return this.editor.document.getText();
 
     };

src/command/CommandManager.js

@@ -19,6 +19,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
  /**
   * Manages global application commands that can be called from menu items, key bindings, or subparts
   * of the application.
@@ -40,14 +42,16 @@ define(function (require, exports, module) {
 
     /**
      * Map of all registered global commands
-     * @type {Object.<commandID: string, Command>}
+     * @type {Object} CommandMap
+     * @property {Object.<string, Command>} commands - A map of command IDs to Command objects.
      */
     let _commands = {};
 
     /**
      * Temporary copy of commands map for restoring after testing
      * TODO (issue #1039): implement separate require contexts for unit tests
-     * @type {Object.<commandID: string, Command>}
+     * @type {Object} CommandMap
+     * @property {Object.<string, Command>} commands - A map of command IDs to Command objects.
      */
     let _commandsOriginal = {};
 

src/command/DefaultMenus.js

@@ -21,6 +21,8 @@
 
 /*global Phoenix*/
 
+// @INCLUDE_IN_API_DOCS
+
 /**
  * Initializes the default brackets menu items.
  */