📝 Convert Config docs

2026-01-23 05:48:10 -05:00 · 2014-08-20 12:31:53 -06:00
parent c2fa20c543
commit 0079007bb6
1 changed files with 40 additions and 43 deletions
--- 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(/\./, '-')}")