From 8d193d542bf923489855b9d026eef0f2e82b2fee Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Tue, 21 Jan 2014 20:56:30 -0700
Subject: [PATCH] Update configuration docs

---
 docs/internals/configuration.md | 39 +++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/docs/internals/configuration.md b/docs/internals/configuration.md
index b70493dc1..37048f3d0 100644
--- a/docs/internals/configuration.md
+++ b/docs/internals/configuration.md
@@ -3,14 +3,15 @@
 ### Reading Config Settings
 
 If you are writing a package that you want to make configurable, you'll need to
-read config settings. You can read a value from `config` with `config.get`:
+read config settings via the `atom.config` global. You can read the current
+value of a namespaced config key with `atom.config.get`:
 
 ```coffeescript
 # read a value with `config.get`
 @showInvisibles() if config.get "edtior.showInvisibles"
 ```
 
-Or you can use `observeConfig` to track changes from a view object.
+Or you can use the `::observeConfig` to track changes from any view object.
 
 ```coffeescript
 class MyView extends View
@@ -19,7 +20,7 @@ class MyView extends View
       @adjustFontSize()
 ```
 
-The `observeConfig` method will call the given callback immediately with the
+The `::observeConfig` method will call the given callback immediately with the
 current value for the specified key path, and it will also call it in the future
 whenever the value of that key path changes.
 
@@ -35,26 +36,40 @@ You can add the ability to observe config values to non-view classes by
 extending their prototype with the `ConfigObserver` mixin:
 
 ```coffeescript
-ConfigObserver = require 'config-observer'
-_.extend MyClass.prototype, ConfigObserver
+{ConfigObserver} = require 'atom'
+
+class MyClass
+  ConfigObserver.includeInto(this)
+  
+  constructor: ->
+    @observeConfig 'editor.showInvisibles', -> # ...
+
+  destroy: ->
+    @unobserveConfig()
 ```
 
 ### Writing Config Settings
 
-As discussed above, the config database is automatically populated from
-`config.cson` when Atom is started, but you can programmatically write to it in
-the following way:
+The `atom.config` database is populated on startup from `~/.atom/config.cson`,
+but you can programmatically write to it with `atom.config.set`:
 
 ```coffeescript
 # basic key update
-config.set("core.showInvisibles", true)
+atom.config.set("core.showInvisibles", true)
+```
 
-config.pushAtKeyPath("core.disabledPackages", "wrap-guide")
+You should never mutate the value of a config key, because that would circumvent
+the notification of observers. You can however use methods like `pushAtKeyPath`,
+`unshiftAtKeyPath`, and `removeAtKeyPath` to manipulate mutable config values.
+
+```coffeescript
+atom.config.pushAtKeyPath("core.disabledPackages", "wrap-guide")
+atom.config.removeAtKeyPath("core.disabledPackages", "terminal")
 ```
 
 You can also use `setDefaults`, which will assign default values for keys that
-are always overridden by values assigned with `set`. Defaults are not written out
-to the the `config.json` file to prevent it from becoming cluttered.
+are always overridden by values assigned with `set`. Defaults are not written
+out to the the `config.json` file to prevent it from becoming cluttered.
 
 ```coffeescript
 config.setDefaults("editor", fontSize: 18, showInvisibles: true)