 userPackageDirPaths.unshift(path.join(configDirPath, "dev", "packages")) if atom.getLoadSettings().devMode
 userStoragePath = path.join(configDirPath, "storage")
 
-# Public: Handles all of Atom's configuration details.
-#
-# This includes loading and setting default options, as well as reading from the
-# user's configuration file.
+# Public: Used to access all of Atom's configuration details.
+#
+# A global instance of this class is available to all plugins which can be
+# referenced using `global.config`
+#
+# ### Best practices ###
+#
+# * Create your own root keypath using your package's name.
+# * Don't depend on (or write to) configuration keys outside of your keypath.
+#
+# ### Example ###
+#
+# ```coffeescript
+# global.config.set('myplugin.key', 'value')
+# global.observe 'myplugin.key', ->
+#   console.log 'My configuration changed:', global.config.get('myplugin.key')
+# ```
 module.exports =
 class Config
   _.extend @prototype, EventEmitter

      queue.push({sourcePath, destinationPath})
    fsUtils.traverseTree(templateConfigDirPath, onConfigDirFile, (path) -> true)

  load: ->
    @initializeConfigDirectory()
    @loadUserConfig()
    @observeUserConfig()

  loadUserConfig: ->
    if !fsUtils.exists(@configFilePath)
      fsUtils.makeTree(path.dirname(@configFilePath))

      console.error "Failed to load user config '#{@configFilePath}'", e.message
      console.error e.stack

  # Private:
  observeUserConfig: ->
    @watchSubscription ?= pathWatcher.watch @configFilePath, (eventType) =>
      @loadUserConfig() if eventType is 'change' and @watchSubscription?

  # Private:
  unobserveUserConfig: ->
    @watchSubscription?.close()
    @watchSubscription = null

  # Private:
  setDefaults: (keyPath, defaults) ->
    keys = keyPath.split('.')
    hash = @defaultSettings
