1919 *
2020 */
2121
22+ //@INCLUDE_IN_API_DOCS
23+
2224/*global Phoenix*/
2325
2426/*
@@ -84,6 +86,7 @@ define(function (require, exports, module) {
8486
8587/**
8688 * Read in the json files that have type information for the builtins, dom,etc
89+ *@private
8790 */
8891function initTernEnv ( ) {
8992const builtinDefinitionFiles = JSON . parse ( require ( "text!thirdparty/tern/defs/defs.json" ) ) ;
@@ -108,7 +111,7 @@ define(function (require, exports, module) {
108111/**
109112 * Init preferences from a file in the project root or builtin
110113 * defaults if no file is found;
111- *
114+ *@private
112115 *@param {string= } projectRootPath - new project root path. Only needed
113116 * for unit tests.
114117 */
@@ -164,7 +167,7 @@ define(function (require, exports, module) {
164167
165168/**
166169 * Will initialize preferences only if they do not exist.
167- *
170+ *@private
168171 */
169172function ensurePreferences ( ) {
170173if ( ! deferredPreferences ) {
@@ -184,7 +187,7 @@ define(function (require, exports, module) {
184187
185188/**
186189 * Test if the directory should be excluded from analysis.
187- *
190+ *@private
188191 *@param {!string } path - full directory path.
189192 *@return {boolean } true if excluded, false otherwise.
190193 */
@@ -203,7 +206,7 @@ define(function (require, exports, module) {
203206
204207/**
205208 * Test if the file path is in current editor
206- *
209+ *@private
207210 *@param {string } filePath file path to test for exclusion.
208211 *@return {boolean } true if in editor, false otherwise.
209212 */
@@ -216,7 +219,7 @@ define(function (require, exports, module) {
216219
217220/**
218221 * Test if the file path is an internal exclusion.
219- *
222+ *@private
220223 *@param {string } path file path to test for exclusion.
221224 *@return {boolean } true if excluded, false otherwise.
222225 */
@@ -233,7 +236,7 @@ define(function (require, exports, module) {
233236
234237/**
235238 * Test if the file should be excluded from analysis.
236- *
239+ *@private
237240 *@param {!File } file - file to test for exclusion.
238241 *@return {boolean } true if excluded, false otherwise.
239242 */
@@ -326,6 +329,7 @@ define(function (require, exports, module) {
326329
327330/**
328331 * Get a Promise for the definition from TernJS, for the file & offset passed in.
332+ *@private
329333 *@param {{type: string, name: string, offsetLines: number, text: string} } fileInfo
330334 * - type of update, name of file, and the text of the update.
331335 * For "full" updates, the whole text of the file is present. For "part" updates,
@@ -361,6 +365,7 @@ define(function (require, exports, module) {
361365/**
362366 * Get the text of a document, applying any size restrictions
363367 * if necessary
368+ *@private
364369 *@param {Document } document - the document to get the text from
365370 *@return {string } the text, or the empty text if the original was too long
366371 */
@@ -373,7 +378,7 @@ define(function (require, exports, module) {
373378/**
374379 * Handle the response from the tern node domain when
375380 * it responds with the references
376- *
381+ *@private
377382 *@param response - the response from the node domain
378383 */
379384function handleRename ( response ) {
@@ -421,7 +426,7 @@ define(function (require, exports, module) {
421426/**
422427 * Handle the response from the tern node domain when
423428 * it responds with the definition
424- *
429+ *@private
425430 *@param response - the response from the node domain
426431 */
427432function handleJumptoDef ( response ) {
@@ -440,7 +445,7 @@ define(function (require, exports, module) {
440445/**
441446 * Handle the response from the tern node domain when
442447 * it responds with the scope data
443- *
448+ *@private
444449 *@param response - the response from the node domain
445450 */
446451function handleScopeData ( response ) {
@@ -486,6 +491,7 @@ define(function (require, exports, module) {
486491
487492/**
488493 * Get a Promise for the function type from TernJS.
494+ *@private
489495 *@param {{type: string, name: string, offsetLines: number, text: string} } fileInfo
490496 * - type of update, name of file, and the text of the update.
491497 * For "full" updates, the whole text of the file is present. For "part" updates,
@@ -508,7 +514,7 @@ define(function (require, exports, module) {
508514/**
509515 * Given a starting and ending position, get a code fragment that is self contained
510516 * enough to be compiled.
511- *
517+ *@private
512518 *@param {!Session } session - the current session
513519 *@param {{line: number, ch: number} } start - the starting position of the changes
514520 *@return {{type: string, name: string, offsetLines: number, text: string} }
@@ -578,7 +584,7 @@ define(function (require, exports, module) {
578584 * Get an object that describes what tern needs to know about the updated
579585 * file to produce a hint. As a side-effect of this calls the document
580586 * changes are reset.
581- *
587+ *@private
582588 *@param {!Session } session - the current session
583589 *@param {boolean= } preventPartialUpdates - if true, disallow partial updates.
584590 * Optional, defaults to false.
@@ -617,7 +623,7 @@ define(function (require, exports, module) {
617623
618624/**
619625 * Get the current offset. The offset is adjusted for "part" updates.
620- *
626+ *@private
621627 *@param {!Session } session - the current session
622628 *@param {{type: string, name: string, offsetLines: number, text: string} } fileInfo
623629 * - type of update, name of file, and the text of the update.
@@ -678,7 +684,7 @@ define(function (require, exports, module) {
678684/**
679685 * Handle the response from the tern node domain when
680686 * it responds with the list of completions
681- *
687+ *@private
682688 *@param {{file: string, offset: {line: number, ch: number}, completions:Array.<string>,
683689 * properties:Array.<string> }} response - the response from node domain
684690 */
@@ -709,7 +715,7 @@ define(function (require, exports, module) {
709715/**
710716 * Handle the response from the tern node domain when
711717 * it responds to the get guesses message.
712- *
718+ *@private
713719 *@param {{file: string, type: string, offset: {line: number, ch: number},
714720 * properties: Array.<string> }} response -
715721 * the response from node domain contains the guesses for a
@@ -729,7 +735,7 @@ define(function (require, exports, module) {
729735/**
730736 * Handle the response from the tern node domain when
731737 * it responds to the update file message.
732- *
738+ *@private
733739 *@param {{path: string, type: string} } response - the response from node domain
734740 */
735741function handleUpdateFile ( response ) {
@@ -745,7 +751,7 @@ define(function (require, exports, module) {
745751
746752/**
747753 * Handle timed out inference
748- *
754+ *@private
749755 *@param {{path: string, type: string} } response - the response from node domain
750756 */
751757function handleTimedOut ( response ) {
@@ -807,7 +813,6 @@ define(function (require, exports, module) {
807813 * Encapsulate all the logic to talk to the tern module. This will create
808814 * a new instance of a TernModule, which the rest of the hinting code can use to talk
809815 * to the tern node domain, without worrying about initialization, priming the pump, etc.
810- *
811816 */
812817function TernModule ( ) {
813818var ternPromise = null ,
@@ -831,7 +836,7 @@ define(function (require, exports, module) {
831836/**
832837 * Determine whether the current set of files are using modules to pull in
833838 * additional files.
834- *
839+ *@private
835840 *@return {boolean } - true if more files than the current directory have
836841 * been read in.
837842 */
@@ -855,6 +860,7 @@ define(function (require, exports, module) {
855860/**
856861 * Send a message to the tern node domain - this is only for messages that
857862 * need to be sent before and while the addFilesPromise is being resolved.
863+ *@private
858864 */
859865function _postMessageByPass ( msg ) {
860866ternPromise . done ( function ( ) {
@@ -867,7 +873,7 @@ define(function (require, exports, module) {
867873
868874/**
869875 * Update tern with the new contents of a given file.
870- *
876+ *@private
871877 *@param {Document } document - the document to update
872878 *@return {jQuery.Promise } - the promise for the request
873879 */
@@ -885,7 +891,7 @@ define(function (require, exports, module) {
885891
886892/**
887893 * Handle a request from the tern node domain for text of a file
888- *
894+ *@private
889895 *@param {{file:string} } request - the request from the tern node domain. Should be an Object containing the name
890896 * of the file tern wants the contents of
891897 */
@@ -905,7 +911,7 @@ define(function (require, exports, module) {
905911 * Helper function to get the text of a given document and send it to tern.
906912 * If DocumentManager successfully gets the file's text then we'll send it to the tern node domain.
907913 * The Promise for getDocumentText() is returned so that custom fail functions can be used.
908- *
914+ *@private
909915 *@param {string } filePath - the path of the file to get the text of
910916 *@return {jQuery.Promise } - the Promise returned from DocumentMangaer.getDocumentText()
911917 */
@@ -935,6 +941,7 @@ define(function (require, exports, module) {
935941 * name we are looking for. This is so we can find requirejs modules
936942 * when the baseUrl is unknown, or when the project root is not the same
937943 * as the script root (e.g. if you open the 'brackets' dir instead of 'brackets/src' dir).
944+ *@private
938945 */
939946function findNameInProject ( ) {
940947// check for any files in project that end with the right path.
@@ -979,7 +986,7 @@ define(function (require, exports, module) {
979986
980987/**
981988 * Prime the pump for a fast first lookup.
982- *
989+ *@private
983990 *@param {string } path - full path of file
984991 *@return {jQuery.Promise } - the promise for the request
985992 */
@@ -996,7 +1003,7 @@ define(function (require, exports, module) {
9961003/**
9971004 * Handle the response from the tern node domain when
9981005 * it responds to the prime pump message.
999- *
1006+ *@private
10001007 *@param {{path: string, type: string} } response - the response from node domain
10011008 */
10021009function handlePrimePumpCompletion ( response ) {
@@ -1014,7 +1021,7 @@ define(function (require, exports, module) {
10141021 * Add new files to tern, keeping any previous files.
10151022 * The tern server must be initialized before making
10161023 * this call.
1017- *
1024+ *@private
10181025 *@param {Array.<string> } files - array of file to add to tern.
10191026 *@return {boolean } - true if more files may be added, false if maximum has been reached.
10201027 */
@@ -1051,7 +1058,7 @@ define(function (require, exports, module) {
10511058/**
10521059 * Add the files in the directory and subdirectories of a given directory
10531060 * to tern.
1054- *
1061+ *@private
10551062 *@param {string } dir - the root directory to add.
10561063 *@param {function () } doneCallback - called when all files have been
10571064 * added to tern.
@@ -1085,6 +1092,7 @@ define(function (require, exports, module) {
10851092
10861093/**
10871094 * Init the Tern module that does all the code hinting work.
1095+ *@private
10881096 */
10891097function initTernModule ( ) {
10901098let moduleDeferred = $ . Deferred ( ) ;
@@ -1145,6 +1153,7 @@ define(function (require, exports, module) {
11451153
11461154/**
11471155 * Create a new tern server.
1156+ *@private
11481157 */
11491158function initTernServer ( dir , files ) {
11501159initTernModule ( ) ;
@@ -1169,7 +1178,7 @@ define(function (require, exports, module) {
11691178/**
11701179 * We can skip tern initialization if we are opening a file that has
11711180 * already been added to tern.
1172- *
1181+ *@private
11731182 *@param {string } newFile - full path of new file being opened in the editor.
11741183 *@return {boolean } - true if tern initialization should be skipped,
11751184 * false otherwise.
@@ -1181,7 +1190,7 @@ define(function (require, exports, module) {
11811190
11821191/**
11831192 * Do the work to initialize a code hinting session.
1184- *
1193+ *@private
11851194 *@param {Session } session - the active hinting session (TODO: currently unused)
11861195 *@param {!Document } document - the document the editor has changed to
11871196 *@param {?Document } previousDocument - the document the editor has changed from
@@ -1312,6 +1321,7 @@ define(function (require, exports, module) {
13121321 *
13131322 * We can clean up the node tern server we use to calculate hints now, since
13141323 * we know we will need to re-init it in any new project that is opened.
1324+ *@private
13151325 */
13161326function resetModule ( ) {
13171327function resetTernServer ( ) {
@@ -1347,11 +1357,12 @@ define(function (require, exports, module) {
13471357 *
13481358 * During debugging, you can turn this automatic resetting behavior off
13491359 * by running this in the console:
1360+ * ```js
13501361 * brackets._configureJSCodeHints({ noReset: true })
1351- *
1362+ * ```
13521363 * This function is also used in unit testing with the "force" flag to
13531364 * reset the module for each test to start with a clean environment.
1354- *
1365+ *@private
13551366 *@param {Session } session
13561367 *@param {Document } document
13571368 *@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) {
14681479/**
14691480 * Track the update area of the current document so we can tell if we can send
14701481 * partial updates to tern or not.
1471- *
1472- *@param {Array.<{from: {line:number, ch: number}, to: {line:number, ch: number},
1473- * text: Array<string>}> } changeList - the document changes from the current change event
1482+ *@param {{from: {line: number, ch: number}, to: {line: number, ch: number}, text: string[]} } changeList - The document changes from the current change event
1483+ *@private
14741484 */
14751485function trackChange ( changeList ) {
14761486var changed = documentChanges , i ;
@@ -1498,11 +1508,10 @@ define(function (require, exports, module) {
14981508}
14991509}
15001510
1501- /*
1511+ /**
15021512 * Called each time the file associated with the active editor changes.
15031513 * Marks the file as being dirty.
1504- *
1505- *@param {from: {line:number, ch: number}, to: {line:number, ch: number} }
1514+ *@param {{line:number, ch: number} } changeList - An object representing the change range with `from` and `to` properties, each containing `line` and `ch` numbers.
15061515 */
15071516function handleFileChange ( changeList ) {
15081517isDocumentDirty = true ;
@@ -1546,7 +1555,10 @@ define(function (require, exports, module) {
15461555initPreferences ( projectRootPath ) ;
15471556}
15481557
1549- /** Used to avoid timing bugs in unit tests */
1558+ /**
1559+ * Used to avoid timing bugs in unit tests
1560+ *@private
1561+ */
15501562function _readyPromise ( ) {
15511563return deferredPreferences ;
15521564}