From d79eb8eed364ac76e7c31f88266a69a57d722fe2 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Thu, 21 Aug 2014 18:19:52 -0700
Subject: [PATCH] Update decoration docs

---
 src/decoration.coffee | 71 ++++++++++++++++++++++++++-----------------
 1 file changed, 43 insertions(+), 28 deletions(-)

diff --git a/src/decoration.coffee b/src/decoration.coffee
index 96acfcee1..18671f465 100644
--- a/src/decoration.coffee
+++ b/src/decoration.coffee
@@ -4,7 +4,7 @@ _ = require 'underscore-plus'
 idCounter = 0
 nextId = -> idCounter++
 
-# Public: Represents a decoration that follows a {Marker}. A decoration is
+# Essential: Represents a decoration that follows a {Marker}. A decoration is
 # basically a visual representation of a marker. It allows you to add CSS
 # classes to line numbers in the gutter, lines, and add selection-line regions
 # around marked ranges of text.
@@ -20,17 +20,15 @@ nextId = -> idCounter++
 #
 # Best practice for destorying the decoration is by destroying the {Marker}.
 #
-# ```
+# ```coffee
 # marker.destroy()
 # ```
 #
 # You should only use {Decoration::destroy} when you still need or do not own
 # the marker.
 #
-# ### IDs
-# Each {Decoration} has a unique ID available via `decoration.id`.
+# ## Events
 #
-# ### Events
 # A couple of events are emitted:
 #
 # * `destroyed`: When the {Decoration} is destroyed
@@ -41,6 +39,14 @@ module.exports =
 class Decoration
   Emitter.includeInto(this)
 
+  # Extended: Check if the `decorationParams.type` matches `type`
+  #
+  # * `decorationParams` {Object} eg. `{type: 'gutter', class: 'my-new-class'}`
+  # * `type` {String} type like `'gutter'`, `'line'`, etc. `type` can also
+  #          be an {Array} of {String}s, where it will return
+  #          true if the decoration's type matches any in the array.
+  #
+  # Returns {Boolean}
   @isType: (decorationParams, type) ->
     if _.isArray(decorationParams.type)
       type in decorationParams.type
@@ -53,21 +59,34 @@ class Decoration
     @flashQueue = null
     @isDestroyed = false
 
-  # Public: Destroy this marker.
-  #
-  # If you own the marker, you should use {Marker::destroy} which will destroy
-  # this decoration.
-  destroy: ->
-    return if @isDestroyed
-    @isDestroyed = true
-    @displayBuffer.removeDecoration(this)
-    @emit 'destroyed'
+  # Essential: An id unique across all {Decoration} objects
+  getId: -> @id
 
-  # Public: Update the marker with new params. Allows you to change the decoration's class.
+  # Essential: Returns the marker associated with this {Decoration}
+  getMarker: -> @marker
+
+  # Essential: Returns the {Decoration}'s params.
+  getParams: -> @params
+
+  # Public: Check if this decoration is of type `type`
   #
-  # ```
+  # * `type` {String} type like `'gutter'`, `'line'`, etc. `type` can also
+  #          be an {Array} of {String}s, where it will return
+  #          true if the decoration's type matches any in the array.
+  #
+  # Returns {Boolean}
+  isType: (type) ->
+    Decoration.isType(@params, type)
+
+  # Essential: Update the marker with new params. Allows you to change the decoration's class.
+  #
+  # ## Examples
+  #
+  # ```coffee
   # decoration.update({type: 'gutter', class: 'my-new-class'})
   # ```
+  #
+  # * `newParams` {Object} eg. `{type: 'gutter', class: 'my-new-class'}`
   update: (newParams) ->
     return if @isDestroyed
     oldParams = @params
@@ -76,19 +95,15 @@ class Decoration
     @displayBuffer.decorationUpdated(this)
     @emit 'updated', {oldParams, newParams}
 
-  # Public: Returns the marker associated with this {Decoration}
-  getMarker: -> @marker
-
-  # Public: Returns the {Decoration}'s params.
-  getParams: -> @params
-
-  # Public: Check if this decoration is of type `type`
+  # Essential: Destroy this marker.
   #
-  # type - A {String} type like `'gutter'`
-  #
-  # Returns a {Boolean}
-  isType: (type) ->
-    Decoration.isType(@params, type)
+  # If you own the marker, you should use {Marker::destroy} which will destroy
+  # this decoration.
+  destroy: ->
+    return if @isDestroyed
+    @isDestroyed = true
+    @displayBuffer.removeDecoration(this)
+    @emit 'destroyed'
 
   matchesPattern: (decorationPattern) ->
     return false unless decorationPattern?