From 7b1fe94e47e6f5f667e256fee71dff8e722d048a Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Mon, 1 Oct 2012 12:27:12 -1000
Subject: [PATCH] Add `$.fn.document`, which associates event-listeners with
 descriptions

`$.fn.events` now returns an array of event-name/description pairs.
---
 spec/stdlib/jquery-extensions-spec.coffee | 30 +++++++++++++++++++----
 src/stdlib/jquery-extensions.coffee       |  9 ++++++-
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/spec/stdlib/jquery-extensions-spec.coffee b/spec/stdlib/jquery-extensions-spec.coffee
index 05991df4c..00a12ea18 100644
--- a/spec/stdlib/jquery-extensions-spec.coffee
+++ b/spec/stdlib/jquery-extensions-spec.coffee
@@ -41,19 +41,39 @@ describe 'jQuery extensions', ->
         element.trigger 'foo'
         expect(events).toEqual [2,1,3]
 
-  describe "$.fn.events()", ->
-    fit "returns a list of all events being listened for on the target node or its ancestors", ->
+  describe "$.fn.events() and $.fn.document", ->
+    fit "returns a list of all events being listened for on the target node or its ancestors, along with their documentation string", ->
       view = $$ ->
         @div id: 'a', =>
           @div id: 'b', =>
             @div id: 'c'
           @div id: 'd'
 
+      view.document 'A1'
+
+      view.document
+        'a1': "This is event A2"
+        'b2': "This is event b2"
+
+      view.document 'a1': "A1: Waste perfectly-good steak"
       view.on 'a1', ->
       view.on 'a2', ->
-      view.find('#b').on 'b1', ->
-      view.find('#b').on 'b2', ->
+
+      divB = view.find('#b')
+
+      divB.document
+        'b1': "B1: Super-sonic bomber"
+        'b2': "B2: Looks evil. Kinda is."
+      divB.on 'b1', ->
+      divB.on 'b2', ->
+
       view.find('#c').on 'c', ->
       view.find('#d').on 'd', ->
 
-      expect(view.find('#c').events()).toEqual ['c', 'b1', 'b2', 'a1', 'a2']
\ No newline at end of file
+      expect(view.find('#c').events()).toEqual [
+        ['c'],
+        ['b1', "B1: Super-sonic bomber"],
+        ['b2', "B2: Looks evil. Kinda is."],
+        ['a1', "A1: Waste perfectly-good steak"],
+        ['a2']
+      ]
\ No newline at end of file
diff --git a/src/stdlib/jquery-extensions.coffee b/src/stdlib/jquery-extensions.coffee
index f937ba2e6..4852beffa 100644
--- a/src/stdlib/jquery-extensions.coffee
+++ b/src/stdlib/jquery-extensions.coffee
@@ -38,8 +38,15 @@ $.fn.trueHeight = ->
 $.fn.trueWidth = ->
   this[0].getBoundingClientRect().width
 
+$.fn.document = (eventDescriptions) ->
+  @data('documentation', {}) unless @data('documentation')
+  _.extend(@data('documentation'), eventDescriptions)
+
 $.fn.events = ->
-  events = _.keys(@data('events') ? {})
+  documentation = @data('documentation') ? {}
+  events = _.keys(@data('events') ? {}).map (eventName) ->
+    _.compact([eventName, documentation[eventName]])
+
   if @hasParent()
     events.concat(@parent().events())
   else