Publicize and document StyleManager

src/atom.coffee

@@ -137,6 +137,9 @@ class Atom extends Model
   # Public: A {ThemeManager} instance
   themes: null
 
+  # Public: A {StyleManager} instance
+  styles: null
+
   # Public: A {DeserializerManager} instance
   deserializers: null
 

src/style-manager.coffee

@@ -1,5 +1,10 @@
 {Emitter, Disposable} = require 'event-kit'
 
+# Extended: A singleton instance of this class available via `atom.styles`,
+# which you can use to globally query and observe the set of active style
+# sheets. The `StyleManager` doesn't add any style elements to the DOM on its
+# own, but is instead subscribed to by individual `<atom-styles>` elements,
+# which clone and attach style elements in different contexts.
 module.exports =
 class StyleManager
   constructor: ->
@@ -7,19 +12,78 @@ class StyleManager
     @styleElements = []
     @styleElementsBySourcePath = {}
 
+  ###
+  Section: Event Subscription
+  ###
+
+  # Extended: Invoke `callback` for all current and future style elements.
+  #
+  # * `callback` {Function} that is called with style elements.
+  #   * `styleElement` An `HTMLStyleElement` instance. The `.sheet` property
+  #     will be null because this element isn't attached to the DOM. If you want
+  #     to attach this element to the DOM, be sure to clone it first by calling
+  #     `.cloneNode(true)` on it. The style element will also have the following
+  #     non-standard properties:
+  #     * `sourcePath` A {String} containing the path from which the style
+  #       element was loaded.
+  #     * `context` A {String} indicating the target context of the style
+  #       element.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to cancel the
+  # subscription.
   observeStyleElements: (callback) ->
     callback(styleElement) for styleElement in @getStyleElements()
     @onDidAddStyleElement(callback)
 
+  # Extended: Invoke `callback` when a style element is added.
+  #
+  # * `callback` {Function} that is called with style elements.
+  #   * `styleElement` An `HTMLStyleElement` instance. The `.sheet` property
+  #     will be null because this element isn't attached to the DOM. If you want
+  #     to attach this element to the DOM, be sure to clone it first by calling
+  #     `.cloneNode(true)` on it. The style element will also have the following
+  #     non-standard properties:
+  #     * `sourcePath` A {String} containing the path from which the style
+  #       element was loaded.
+  #     * `context` A {String} indicating the target context of the style
+  #       element.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to cancel the
+  # subscription.
   onDidAddStyleElement: (callback) ->
     @emitter.on 'did-add-style-element', callback
 
+  # Extended: Invoke `callback` when a style element is removed.
+  #
+  # * `callback` {Function} that is called with style elements.
+  #   * `styleElement` An `HTMLStyleElement` instance.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to cancel the
+  # subscription.
   onDidRemoveStyleElement: (callback) ->
     @emitter.on 'did-remove-style-element', callback
 
+  # Extended: Invoke `callback` when an existing style element is updated.
+  #
+  # * `callback` {Function} that is called with style elements.
+  #   * `styleElement` An `HTMLStyleElement` instance. The `.sheet` property
+  #      will be null because this element isn't attached to the DOM. The style
+  #      element will also have the following non-standard properties:
+  #     * `sourcePath` A {String} containing the path from which the style
+  #       element was loaded.
+  #     * `context` A {String} indicating the target context of the style
+  #       element.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to cancel the
+  # subscription.
   onDidUpdateStyleElement: (callback) ->
     @emitter.on 'did-update-style-element', callback
 
+  ###
+  Section: Reading Style Elements
+  ###
+
+  # Extended: Get all loaded style elements.
   getStyleElements: ->
     @styleElements.slice()