deploy: 84352e3

Author: phoenixide

JSUtils/Preferences.js

@@ -19,6 +19,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 /**
 
     This class parses configuration values from a JSON object. The expected
@@ -68,7 +70,7 @@ define(function (require, exports, module) {
     /**
      *  Convert an array of strings with optional wildcards, to an equivalent
      *  regular expression.
-     *
+     * @private
      * @param {Array.<string|RegExp>} settings from the file (note: this may be mutated by this function)
      * @param {?RegExp} baseRegExp - base regular expression that is always used
      * @param {?RegExp} defaultRegExp - additional regular expression that is only used if the user has not configured settings

JSUtils/ScopeManager.js

@@ -19,6 +19,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 /*global Phoenix*/
 
 /*
@@ -84,6 +86,7 @@ define(function (require, exports, module) {
 
     /**
      * Read in the json files that have type information for the builtins, dom,etc
+     * @private
      */
     function initTernEnv() {
         const builtinDefinitionFiles = JSON.parse(require("text!thirdparty/tern/defs/defs.json"));
@@ -108,7 +111,7 @@ define(function (require, exports, module) {
     /**
      *  Init preferences from a file in the project root or builtin
      *  defaults if no file is found;
-     *
+     * @private
      *  @param {string=} projectRootPath - new project root path. Only needed
      *  for unit tests.
      */
@@ -164,7 +167,7 @@ define(function (require, exports, module) {
 
     /**
      * Will initialize preferences only if they do not exist.
-     *
+     * @private
      */
     function ensurePreferences() {
         if (!deferredPreferences) {
@@ -184,7 +187,7 @@ define(function (require, exports, module) {
 
     /**
      * Test if the directory should be excluded from analysis.
-     *
+     * @private
      * @param {!string} path - full directory path.
      * @return {boolean} true if excluded, false otherwise.
      */
@@ -203,7 +206,7 @@ define(function (require, exports, module) {
 
     /**
      * Test if the file path is in current editor
-     *
+     * @private
      * @param {string} filePath file path to test for exclusion.
      * @return {boolean} true if in editor, false otherwise.
      */
@@ -216,7 +219,7 @@ define(function (require, exports, module) {
 
     /**
      * Test if the file path is an internal exclusion.
-     *
+     * @private
      * @param {string} path file path to test for exclusion.
      * @return {boolean} true if excluded, false otherwise.
      */
@@ -233,7 +236,7 @@ define(function (require, exports, module) {
 
     /**
      * Test if the file should be excluded from analysis.
-     *
+     * @private
      * @param {!File} file - file to test for exclusion.
      * @return {boolean} true if excluded, false otherwise.
      */
@@ -326,6 +329,7 @@ define(function (require, exports, module) {
 
     /**
      * Get a Promise for the definition from TernJS, for the file & offset passed in.
+     * @private
      * @param {{type: string, name: string, offsetLines: number, text: string}} fileInfo
      * - type of update, name of file, and the text of the update.
      * For "full" updates, the whole text of the file is present. For "part" updates,
@@ -361,6 +365,7 @@ define(function (require, exports, module) {
     /**
      * Get the text of a document, applying any size restrictions
      * if necessary
+     * @private
      * @param {Document} document - the document to get the text from
      * @return {string} the text, or the empty text if the original was too long
      */
@@ -373,7 +378,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds with the references
-     *
+     * @private
      * @param response - the response from the node domain
      */
     function handleRename(response) {
@@ -421,7 +426,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds with the definition
-     *
+     * @private
      * @param response - the response from the node domain
      */
     function handleJumptoDef(response) {
@@ -440,7 +445,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds with the scope data
-     *
+     * @private
      * @param response - the response from the node domain
      */
     function handleScopeData(response) {
@@ -486,6 +491,7 @@ define(function (require, exports, module) {
 
     /**
      * Get a Promise for the function type from TernJS.
+     * @private
      * @param {{type: string, name: string, offsetLines: number, text: string}} fileInfo
      * - type of update, name of file, and the text of the update.
      * For "full" updates, the whole text of the file is present. For "part" updates,
@@ -508,7 +514,7 @@ define(function (require, exports, module) {
     /**
      *  Given a starting and ending position, get a code fragment that is self contained
      *  enough to be compiled.
-     *
+     * @private
      * @param {!Session} session - the current session
      * @param {{line: number, ch: number}} start - the starting position of the changes
      * @return {{type: string, name: string, offsetLines: number, text: string}}
@@ -578,7 +584,7 @@ define(function (require, exports, module) {
      * Get an object that describes what tern needs to know about the updated
      * file to produce a hint. As a side-effect of this calls the document
      * changes are reset.
-     *
+     * @private
      * @param {!Session} session - the current session
      * @param {boolean=} preventPartialUpdates - if true, disallow partial updates.
      * Optional, defaults to false.
@@ -617,7 +623,7 @@ define(function (require, exports, module) {
 
     /**
      *  Get the current offset. The offset is adjusted for "part" updates.
-     *
+     * @private
      * @param {!Session} session - the current session
      * @param {{type: string, name: string, offsetLines: number, text: string}} fileInfo
      * - type of update, name of file, and the text of the update.
@@ -678,7 +684,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds with the list of completions
-     *
+     * @private
      * @param {{file: string, offset: {line: number, ch: number}, completions:Array.<string>,
      *          properties:Array.<string>}} response - the response from node domain
      */
@@ -709,7 +715,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds to the get guesses message.
-     *
+     * @private
      * @param {{file: string, type: string, offset: {line: number, ch: number},
      *      properties: Array.<string>}} response -
      *      the response from node domain contains the guesses for a
@@ -729,7 +735,7 @@ define(function (require, exports, module) {
     /**
      * Handle the response from the tern node domain when
      * it responds to the update file message.
-     *
+     * @private
      * @param {{path: string, type: string}} response - the response from node domain
      */
     function handleUpdateFile(response) {
@@ -745,7 +751,7 @@ define(function (require, exports, module) {
 
     /**
      * Handle timed out inference
-     *
+     * @private
      * @param {{path: string, type: string}} response - the response from node domain
      */
     function handleTimedOut(response) {
@@ -807,7 +813,6 @@ define(function (require, exports, module) {
      * Encapsulate all the logic to talk to the tern module.  This will create
      * a new instance of a TernModule, which the rest of the hinting code can use to talk
      * to the tern node domain, without worrying about initialization, priming the pump, etc.
-     *
      */
     function TernModule() {
         var ternPromise         = null,
@@ -831,7 +836,7 @@ define(function (require, exports, module) {
         /**
          *  Determine whether the current set of files are using modules to pull in
          *  additional files.
-         *
+         * @private
          * @return {boolean} - true if more files than the current directory have
          * been read in.
          */
@@ -855,6 +860,7 @@ define(function (require, exports, module) {
         /**
          * Send a message to the tern node domain - this is only for messages that
          * need to be sent before and while the addFilesPromise is being resolved.
+         * @private
          */
         function _postMessageByPass(msg) {
             ternPromise.done(function () {
@@ -867,7 +873,7 @@ define(function (require, exports, module) {
 
         /**
          *  Update tern with the new contents of a given file.
-         *
+         * @private
          * @param {Document} document - the document to update
          * @return {jQuery.Promise} - the promise for the request
          */
@@ -885,7 +891,7 @@ define(function (require, exports, module) {
 
         /**
          * Handle a request from the tern node domain for text of a file
-         *
+         * @private
          * @param {{file:string}} request - the request from the tern node domain.  Should be an Object containing the name
          *      of the file tern wants the contents of
          */
@@ -905,7 +911,7 @@ define(function (require, exports, module) {
              * Helper function to get the text of a given document and send it to tern.
              * If DocumentManager successfully gets the file's text then we'll send it to the tern node domain.
              * The Promise for getDocumentText() is returned so that custom fail functions can be used.
-             *
+             * @private
              * @param {string} filePath - the path of the file to get the text of
              * @return {jQuery.Promise} - the Promise returned from DocumentMangaer.getDocumentText()
              */
@@ -935,6 +941,7 @@ define(function (require, exports, module) {
              * name we are looking for.  This is so we can find requirejs modules
              * when the baseUrl is unknown, or when the project root is not the same
              * as the script root (e.g. if you open the 'brackets' dir instead of 'brackets/src' dir).
+             * @private
              */
             function findNameInProject() {
                 // check for any files in project that end with the right path.
@@ -979,7 +986,7 @@ define(function (require, exports, module) {
 
         /**
          *  Prime the pump for a fast first lookup.
-         *
+         * @private
          * @param {string} path - full path of file
          * @return {jQuery.Promise} - the promise for the request
          */
@@ -996,7 +1003,7 @@ define(function (require, exports, module) {
         /**
          * Handle the response from the tern node domain when
          * it responds to the prime pump message.
-         *
+         * @private
          * @param {{path: string, type: string}} response - the response from node domain
          */
         function handlePrimePumpCompletion(response) {
@@ -1014,7 +1021,7 @@ define(function (require, exports, module) {
          *  Add new files to tern, keeping any previous files.
          *  The tern server must be initialized before making
          *  this call.
-         *
+         * @private
          * @param {Array.<string>} files - array of file to add to tern.
          * @return {boolean} - true if more files may be added, false if maximum has been reached.
          */
@@ -1051,7 +1058,7 @@ define(function (require, exports, module) {
         /**
          *  Add the files in the directory and subdirectories of a given directory
          *  to tern.
-         *
+         * @private
          * @param {string} dir - the root directory to add.
          * @param {function ()} doneCallback - called when all files have been
          * added to tern.
@@ -1085,6 +1092,7 @@ define(function (require, exports, module) {
 
         /**
          * Init the Tern module that does all the code hinting work.
+         * @private
          */
         function initTernModule() {
             let moduleDeferred = $.Deferred();
@@ -1145,6 +1153,7 @@ define(function (require, exports, module) {
 
         /**
          * Create a new tern server.
+         * @private
          */
         function initTernServer(dir, files) {
             initTernModule();
@@ -1169,7 +1178,7 @@ define(function (require, exports, module) {
         /**
          *  We can skip tern initialization if we are opening a file that has
          *  already been added to tern.
-         *
+         * @private
          * @param {string} newFile - full path of new file being opened in the editor.
          * @return {boolean} - true if tern initialization should be skipped,
          * false otherwise.
@@ -1181,7 +1190,7 @@ define(function (require, exports, module) {
 
         /**
          *  Do the work to initialize a code hinting session.
-         *
+         * @private
          * @param {Session} session - the active hinting session (TODO: currently unused)
          * @param {!Document} document - the document the editor has changed to
          * @param {?Document} previousDocument - the document the editor has changed from
@@ -1312,6 +1321,7 @@ define(function (require, exports, module) {
          *
          * We can clean up the node tern server we use to calculate hints now, since
          * we know we will need to re-init it in any new project that is opened.
+         * @private
          */
         function resetModule() {
             function resetTernServer() {
@@ -1347,11 +1357,12 @@ define(function (require, exports, module) {
      *
      * During debugging, you can turn this automatic resetting behavior off
      * by running this in the console:
+     * ```js
      * brackets._configureJSCodeHints({ noReset: true })
-     *
+     * ```
      * This function is also used in unit testing with the "force" flag to
      * reset the module for each test to start with a clean environment.
-     *
+     * @private
      * @param {Session} session
      * @param {Document} document
      * @param {boolean} force true to force a reset regardless of how long since the last one
@@ -1468,9 +1479,8 @@ define(function (require, exports, module) {
     /**
      *  Track the update area of the current document so we can tell if we can send
      *  partial updates to tern or not.
-     *
-     * @param {Array.<{from: {line:number, ch: number}, to: {line:number, ch: number},
-     *     text: Array<string>}>} changeList - the document changes from the current change event
+     * @param {{from: {line: number, ch: number}, to: {line: number, ch: number}, text: string[]}} changeList - The document changes from the current change event
+     * @private
      */
     function trackChange(changeList) {
         var changed = documentChanges, i;
@@ -1498,11 +1508,10 @@ define(function (require, exports, module) {
         }
     }
 
-    /*
+    /**
      * Called each time the file associated with the active editor changes.
      * Marks the file as being dirty.
-     *
-     * @param {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;
@@ -1546,7 +1555,10 @@ define(function (require, exports, module) {
         initPreferences(projectRootPath);
     }
 
-    /** Used to avoid timing bugs in unit tests */
+    /**
+     * Used to avoid timing bugs in unit tests
+     * @private
+     */
     function _readyPromise() {
         return deferredPreferences;
     }