docs: refine API docs for files in Preferences dir

docs/API-Reference/preferences/PreferencesDialogs.md

@@ -9,25 +9,14 @@ const PreferencesDialogs = brackets.getModule("preferences/PreferencesDialogs")
 PreferencesDialogs
 
 **Kind**: global variable  
-<a name="_validateBaseUrl"></a>
-
-## \_validateBaseUrl(url) ⇒ <code>string</code>
-Validate that text string is a valid base url which should map to a server folder
-
-**Kind**: global function  
-**Returns**: <code>string</code> - Empty string if valid, otherwise error string  
-
-| Param | Type |
-| --- | --- |
-| url | <code>string</code> | 
-
 <a name="showProjectPreferencesDialog"></a>
 
 ## showProjectPreferencesDialog(baseUrl, errorMessage) ⇒ <code>Dialog</code>
 Show a dialog that shows the project preferences
 
 **Kind**: global function  
-**Returns**: <code>Dialog</code> - A Dialog object with an internal promise that will be resolved with the ID     of the clicked button when the dialog is dismissed. Never rejected.  
+**Returns**: <code>Dialog</code> - A Dialog object with an internal promise that will be resolved with the ID
+     of the clicked button when the dialog is dismissed. Never rejected.  
 
 | Param | Type | Description |
 | --- | --- | --- |

docs/API-Reference/preferences/StateManager.md

@@ -8,6 +8,24 @@ const StateManager = brackets.getModule("preferences/StateManager")
 ## \_
 StateManager
 
+**Kind**: global constant  
+<a name="PROJECT_CONTEXT"></a>
+
+## PROJECT\_CONTEXT : <code>string</code>
+Project specific context
+
+**Kind**: global constant  
+<a name="GLOBAL_CONTEXT"></a>
+
+## GLOBAL\_CONTEXT : <code>string</code>
+Global context
+
+**Kind**: global constant  
+<a name="PROJECT_THEN_GLOBAL_CONTEXT"></a>
+
+## PROJECT\_THEN\_GLOBAL\_CONTEXT : <code>string</code>
+Project or global context
+
 **Kind**: global constant  
 <a name="getVal"></a>
 
@@ -43,7 +61,10 @@ Convenience function that sets a view state and then saves the file
 <a name="definePreferenceInternal"></a>
 
 ## definePreferenceInternal(id, type, initial, options) ⇒ <code>Object</code>
-returns a preference instance that can be listened `.on("change", cbfn(changeType))` . The callback fucntion will be calledwhenever there is a change in the supplied id with a changeType argument. The change type can be one of the two:CHANGE_TYPE_INTERNAL - if change is made within the current app window/browser tapCHANGE_TYPE_EXTERNAL - if change is made in a different app window/browser tab
+returns a preference instance that can be listened `.on("change", cbfn(changeType))` . The callback fucntion will be called
+whenever there is a change in the supplied id with a changeType argument. The change type can be one of the two:
+CHANGE_TYPE_INTERNAL - if change is made within the current app window/browser tap
+CHANGE_TYPE_EXTERNAL - if change is made in a different app window/browser tab
 
 **Kind**: global function  
 
@@ -54,3 +75,32 @@ returns a preference instance that can be listened `.on("change", cbfn(changeTyp
 | initial | 
 | options | 
 
+<a name="getPreferenceInternal"></a>
+
+## getPreferenceInternal(id) ⇒ <code>Object</code>
+Get the preference instance for the given ID.
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| id | <code>string</code> | 
+
+<a name="createExtensionStateManager"></a>
+
+## createExtensionStateManager(extensionID) ⇒ <code>object</code>
+create a state manager for an extension.
+ensure that the IDs are unique.
+
+**Kind**: global function  
+**Returns**: <code>object</code> - Object with methods to manage the extension's state and preferences.
+- `get(id, context)`: Get the value from the extension's state.
+- `set(id, value, context)`: Set the value in the extension's state.
+- `definePreference(id, type, initial, options)`: define a preference for the extension.
+- `getPreference(id)`: retrieve a defined preference.
+- `PROJECT_CONTEXT`, `GLOBAL_CONTEXT`, `PROJECT_THEN_GLOBAL_CONTEXT`: constant for context management.  
+
+| Param | Type |
+| --- | --- |
+| extensionID | <code>string</code> | 
+

src/preferences/PreferencesBase.js

@@ -131,6 +131,7 @@ define(function (require, exports, module) {
      * Error type for problems parsing preference files.
      *
      * @constructor
+     * @private
      * @param {string} message Error message
      */
     function ParsingError(message) {
@@ -1022,7 +1023,7 @@ define(function (require, exports, module) {
 
     /**
      * Represents a single, known Preference.
-     *
+     * @private
      * @constructor
      * @param {Object} properties Information about the Preference that is stored on this object
      */
@@ -1037,6 +1038,7 @@ define(function (require, exports, module) {
      * Utility for PreferencesSystem & PrefixedPreferencesSystem -- attach EventDispatcher's on()/off()
      * implementation as private _on_internal()/_off_internal() methods, so the custom on()/off() APIs
      * these classes use can leverage EventDispatcher code internally. Also attach the regular public trigger().
+     * @private
      */
     function _addEventDispatcherImpl(proto) {
         var temp = {};
@@ -1049,7 +1051,7 @@ define(function (require, exports, module) {
     /**
      * Provides a subset of the PreferencesSystem functionality with preference
      * access always occurring with the given prefix.
-     *
+     * @private
      * @constructor
      * @param {PreferencesSystem} base The real PreferencesSystem that is backing this one
      * @param {string} prefix Prefix that is used for preferences lookup. Any separator characters should already be added.
@@ -1063,7 +1065,7 @@ define(function (require, exports, module) {
     PrefixedPreferencesSystem.prototype = {
         /**
          * Defines a new (prefixed) preference.
-         *
+         * @private
          * @param {string} id unprefixed identifier of the preference. Generally a dotted name.
          * @param {string} type Data type for the preference (generally, string, boolean, number)
          * @param {Object} initial Default value for the preference
@@ -1084,7 +1086,7 @@ define(function (require, exports, module) {
 
         /**
          * Get the prefixed preference object
-         *
+         * @private
          * @param {string} id ID of the pref to retrieve.
          */
         getPreference: function (id) {
@@ -1093,7 +1095,7 @@ define(function (require, exports, module) {
 
         /**
          * Gets the prefixed preference
-         *
+         * @private
          * @param {string} id Name of the preference for which the value should be retrieved
          * @param {Object=} context Optional context object to change the preference lookup
          */
@@ -1104,7 +1106,7 @@ define(function (require, exports, module) {
 
         /**
          * Gets the location in which the value of a prefixed preference has been set.
-         *
+         * @private
          * @param {string} id Name of the preference for which the value should be retrieved
          * @param {Object=} context Optional context object to change the preference lookup
          * @return {{scope: string, layer: ?string, layerID: ?object}} Object describing where the preferences came from
@@ -1115,7 +1117,7 @@ define(function (require, exports, module) {
 
         /**
        * Sets the prefixed preference.
-       *
+       * @private
        * @param {string} id - The identifier of the preference to set.
        * @param {Object} value - The new value for the preference.
        * @param {{location: ?Object, context: ?Object}=} options - Specific location to set the value or context for the operation.
@@ -1168,7 +1170,7 @@ define(function (require, exports, module) {
         /**
          * Sets up a listener for events for this PrefixedPreferencesSystem. Only prefixed events
          * will notify. Optionally, you can set up a listener for a specific preference.
-         *
+         * @private
          * @param {string} event Name of the event to listen for
          * @param {string|Function} preferenceID Name of a specific preference or the handler function
          * @param {?Function} handler Handler for the event
@@ -1191,7 +1193,7 @@ define(function (require, exports, module) {
         /**
          * Turns off the event handlers for a given event, optionally for a specific preference
          * or a specific handler function.
-         *
+         * @private
          * @param {string} event Name of the event for which to turn off listening
          * @param {string|Function} preferenceID Name of a specific preference or the handler function
          * @param {?Function} handler Specific handler which should stop being notified
@@ -1213,7 +1215,7 @@ define(function (require, exports, module) {
         /**
          * Saves the preferences. If a save is already in progress, a Promise is returned for
          * that save operation.
-         *
+         * @private
          * @return {Promise} Resolved when the preferences are done saving.
          */
         save: function () {

src/preferences/PreferencesDialogs.js

@@ -40,6 +40,7 @@ define(function (require, exports, module) {
 
     /**
      * Validate that text string is a valid base url which should map to a server folder
+     * @private
      * @param {string} url
      * @return {string} Empty string if valid, otherwise error string
      */

src/preferences/StateManager.js

@@ -33,9 +33,27 @@ define(function (require, exports, module) {
         EventDispatcher = require("utils/EventDispatcher"),
         ProjectManager = require("project/ProjectManager");
 
+    /**
+     * Project specific context
+     * @const
+     * @type {string}
+     */
     const PROJECT_CONTEXT = "project";
+
+    /**
+     * Global context
+     * @const
+     * @type {string}
+     */
     const GLOBAL_CONTEXT = "global";
+
+    /**
+     * Project or global context
+     * @const
+     * @type {string}
+     */
     const PROJECT_THEN_GLOBAL_CONTEXT = "any";
+
     const PHSTORE_STATEMANAGER_PREFIX = "STATE_";
     const transformDotsInID = {};
 
@@ -185,6 +203,12 @@ define(function (require, exports, module) {
         return preference;
     }
 
+    /**
+     * Get the preference instance for the given ID.
+     *
+     * @param {string} id
+     * @returns {{}}
+     */
     function getPreferenceInternal(id) {
         if(!definedPreferences[id]){
             throw new Error("getPreference " + id + " no such preference defined.");
@@ -193,6 +217,19 @@ define(function (require, exports, module) {
     }
 
     const knownExtensions = {};
+
+    /**
+     * create a state manager for an extension.
+     * ensure that the IDs are unique.
+     *
+     * @param {string} extensionID
+     * @returns {object} Object with methods to manage the extension's state and preferences.
+     * - `get(id, context)`: Get the value from the extension's state.
+     * - `set(id, value, context)`: Set the value in the extension's state.
+     * - `definePreference(id, type, initial, options)`: define a preference for the extension.
+     * - `getPreference(id)`: retrieve a defined preference.
+     * - `PROJECT_CONTEXT`, `GLOBAL_CONTEXT`, `PROJECT_THEN_GLOBAL_CONTEXT`: constant for context management.
+     */
     function createExtensionStateManager(extensionID) {
         let i=0;
         if(extensionID.includes(".")){