From 0079007bb6bdc23126ba7ffcc74ee1ca445ad466 Mon Sep 17 00:00:00 2001 From: Kevin Sawicki Date: Wed, 20 Aug 2014 12:31:53 -0600 Subject: [PATCH] :memo: Convert Config docs --- src/config.coffee | 83 +++++++++++++++++++++++------------------------ 1 file changed, 40 insertions(+), 43 deletions(-) diff --git a/src/config.coffee b/src/config.coffee index 2c280aa27..f3606d7bb 100644 --- a/src/config.coffee +++ b/src/config.coffee @@ -15,9 +15,9 @@ pathWatcher = require 'pathwatcher' # * Create your own root keypath using your package's name. # * Don't depend on (or write to) configuration keys outside of your keypath. # -# ## Example +# ## Examples # -# ```coffeescript +# ```coffee # atom.config.set('my-package.key', 'value') # atom.config.observe 'my-package.key', -> # console.log 'My configuration changed:', atom.config.get('my-package.key') @@ -88,17 +88,17 @@ class Config _.extend hash, defaults @emit 'updated' - # Public: Get the {String} path to the config file being used. + # Extended: Get the {String} path to the config file being used. getUserConfigPath: -> @configFilePath - # Public: Returns a new {Object} containing all of settings and defaults. + # Extended: Returns a new {Object} containing all of settings and defaults. getSettings: -> _.deepExtend(@settings, @defaultSettings) - # Public: Retrieves the setting for the given key. + # Essential: Retrieves the setting for the given key. # - # keyPath - The {String} name of the key to retrieve. + # * `keyPath` The {String} name of the key to retrieve. # # Returns the value from Atom's default settings, the user's configuration # file, or `null` if the key doesn't exist in either. @@ -117,19 +117,19 @@ class Config value - # Public: Retrieves the setting for the given key as an integer. + # Extended: Retrieves the setting for the given key as an integer. # - # keyPath - The {String} name of the key to retrieve + # * `keyPath` The {String} name of the key to retrieve # # Returns the value from Atom's default settings, the user's configuration # file, or `NaN` if the key doesn't exist in either. getInt: (keyPath) -> parseInt(@get(keyPath)) - # Public: Retrieves the setting for the given key as a positive integer. + # Extended: Retrieves the setting for the given key as a positive integer. # - # keyPath - The {String} name of the key to retrieve - # defaultValue - The integer {Number} to fall back to if the value isn't + # * `keyPath` The {String} name of the key to retrieve + # * `defaultValue` The integer {Number} to fall back to if the value isn't # positive, defaults to 0. # # Returns the value from Atom's default settings, the user's configuration @@ -137,12 +137,12 @@ class Config getPositiveInt: (keyPath, defaultValue=0) -> Math.max(@getInt(keyPath), 0) or defaultValue - # Public: Sets the value for a configuration setting. + # Essential: Sets the value for a configuration setting. # # This value is stored in Atom's internal configuration file. # - # keyPath - The {String} name of the key. - # value - The value of the setting. + # * `keyPath` The {String} name of the key. + # * `value` The value of the setting. # # Returns the `value`. set: (keyPath, value) -> @@ -153,47 +153,47 @@ class Config @update() value - # Public: Toggle the value at the key path. + # Extended: Toggle the value at the key path. # # The new value will be `true` if the value is currently falsy and will be # `false` if the value is currently truthy. # - # keyPath - The {String} name of the key. + # * `keyPath` The {String} name of the key. # # Returns the new value. toggle: (keyPath) -> @set(keyPath, !@get(keyPath)) - # Public: Restore the key path to its default value. + # Extended: Restore the key path to its default value. # - # keyPath - The {String} name of the key. + # * `keyPath` The {String} name of the key. # # Returns the new value. restoreDefault: (keyPath) -> @set(keyPath, _.valueForKeyPath(@defaultSettings, keyPath)) - # Public: Get the default value of the key path. + # Extended: Get the default value of the key path. # - # keyPath - The {String} name of the key. + # * `keyPath` The {String} name of the key. # # Returns the default value. getDefault: (keyPath) -> defaultValue = _.valueForKeyPath(@defaultSettings, keyPath) _.deepClone(defaultValue) - # Public: Is the key path value its default value? + # Extended: Is the key path value its default value? # - # keyPath - The {String} name of the key. + # * `keyPath` The {String} name of the key. # # Returns a {Boolean}, `true` if the current value is the default, `false` # otherwise. isDefault: (keyPath) -> not _.valueForKeyPath(@settings, keyPath)? - # Public: Push the value to the array at the key path. + # Extended: Push the value to the array at the key path. # - # keyPath - The {String} key path. - # value - The value to push to the array. + # * `keyPath` The {String} key path. + # * `value` The value to push to the array. # # Returns the new array length {Number} of the setting. pushAtKeyPath: (keyPath, value) -> @@ -202,10 +202,10 @@ class Config @set(keyPath, arrayValue) result - # Public: Add the value to the beginning of the array at the key path. + # Extended: Add the value to the beginning of the array at the key path. # - # keyPath - The {String} key path. - # value - The value to shift onto the array. + # * `keyPath` The {String} key path. + # * `value` The value to shift onto the array. # # Returns the new array length {Number} of the setting. unshiftAtKeyPath: (keyPath, value) -> @@ -216,8 +216,8 @@ class Config # Public: Remove the value from the array at the key path. # - # keyPath - The {String} key path. - # value - The value to remove from the array. + # * `keyPath` The {String} key path. + # * `value` The value to remove from the array. # # Returns the new array value of the setting. removeAtKeyPath: (keyPath, value) -> @@ -226,20 +226,17 @@ class Config @set(keyPath, arrayValue) result - # Public: Establishes an event listener for a given key. + # Essential: Add a listener for changes to a given key path. # - # `callback` is fired whenever the value of the key is changed and will - # be fired immediately unless the `callNow` option is `false`. - # - # keyPath - The {String} name of the key to observe - # options - An optional {Object} containing the `callNow` key. - # callback - The {Function} to call when the value of the key changes. - # The first argument will be the new value of the key and the - #   second argument will be an {Object} with a `previous` property - # that is the prior value of the key. + # * `keyPath` The {String} name of the key to observe + # * `options` An optional {Object} containing the `callNow` key. + # * `callback` The {Function} to call when the value of the key changes. + # The first argument will be the new value of the key and the + #   second argument will be an {Object} with a `previous` property + # that is the prior value of the key. # # Returns an {Object} with the following keys: - # :off - A {Function} that unobserves the `keyPath` when called. + # * `off` A {Function} that unobserves the `keyPath` when called. observe: (keyPath, options={}, callback) -> if _.isFunction(options) callback = options @@ -259,9 +256,9 @@ class Config callback(value) if options.callNow ? true subscription - # Public: Unobserve all callbacks on a given key. + # Unobserve all callbacks on a given key. # - # keyPath - The {String} name of the key to unobserve. + # * `keyPath` The {String} name of the key to unobserve. unobserve: (keyPath) -> @off("updated.#{keyPath.replace(/\./, '-')}")