Merge pull request #11262 from sprintr/definepref-docs

abose · abose · commit 41c8fd2bd43c · 2015-06-18T12:14:04.000+05:30
Docs for PreferencesManager.definePreference
diff --git a/src/preferences/PreferencesBase.js b/src/preferences/PreferencesBase.js
@@ -1066,8 +1066,15 @@ define(function (require, exports, module) {
          * @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
-         * @param {?Object} options Additional options for the pref. Can include name and description
-         *                          that will ultimately be used in UI.
+         * @param {?{name: string=, description: string=, validator: function=, excludeFromHints: boolean=, keys: object=, values: array=, valueType: string=}} options
+         *      Additional options for the pref.
+         *      - `options.name`               Name of the preference that can be used in the UI.
+         *      - `options.description`        A description of the preference.
+         *      - `options.validator`          A function to validate the value of a preference.
+         *      - `options.excludeFromHints`   True if you want to exclude a preference from code hints.
+         *      - `options.keys`               An object that will hold the child preferences in case the preference type is `object`
+         *      - `options.values`             An array of possible values of a preference. It will show up in code hints.
+         *      - `options.valueType`          In case the preference type is `array`, `valueType` should hold data type of its elements.
          * @return {Object} The preference object.
          */
         definePreference: function (id, type, initial, options) {
@@ -1290,8 +1297,15 @@ define(function (require, exports, module) {
          * @param {string} id 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
-         * @param {?Object} options Additional options for the pref. Can include name and description
-         *                          that will ultimately be used in UI.
+         * @param {?{name: string=, description: string=, validator: function=, excludeFromHints: boolean=, keys: object=, values: array=, valueType: string=}} options
+         *      Additional options for the pref.
+         *      - `options.name`               Name of the preference that can be used in the UI.
+         *      - `options.description`        A description of the preference.
+         *      - `options.validator`          A function to validate the value of a preference.
+         *      - `options.excludeFromHints`   True if you want to exclude a preference from code hints.
+         *      - `options.keys`               An object that will hold the child preferences in case the preference type is `object`
+         *      - `options.values`             An array of possible values of a preference. It will show up in code hints.
+         *      - `options.valueType`          In case the preference type is `array`, `valueType` should hold data type of its elements.
          * @return {Object} The preference object.
          */
         definePreference: function (id, type, initial, options) {
