Move the utility functions into a Rivets.Util object. Better comment the code for annotated source.

@@ -4,7 +4,7 @@ module.exports = (grunt) ->
 
 
     meta:
     meta:
       banner:
       banner:
-        '// rivets.js\n' +
+        '// Rivets.js\n' +
         '// version: <%= pkg.version %>\n' +
         '// version: <%= pkg.version %>\n' +
         '// author: <%= pkg.author %>\n' +
         '// author: <%= pkg.author %>\n' +
         '// license: <%= pkg.licenses[0].type %>\n'
         '// license: <%= pkg.licenses[0].type %>\n'

-#     rivets.js
-#     version : 0.5.0
-#     author : Michael Richards
-#     license : MIT
+# Rivets.js
+# =========
+
+# > version: 0.5.0
+# > author: Michael Richards
+# > license: MIT
+# >
+# > http://rivetsjs.com/
+
+# ---
 
 
 # The Rivets namespace.
 # The Rivets namespace.
 Rivets = {}
 Rivets = {}
 
 
-# Polyfill For String::trim.
+# Polyfill For `String::trim`.
 unless String::trim then String::trim = -> @replace /^\s+|\s+$/g, ''
 unless String::trim then String::trim = -> @replace /^\s+|\s+$/g, ''
 
 
+# Rivets.Binding
+# --------------
+
 # A single binding between a model attribute and a DOM element.
 # A single binding between a model attribute and a DOM element.
 class Rivets.Binding
 class Rivets.Binding
   # All information about the binding is passed into the constructor; the
   # All information about the binding is passed into the constructor; the
@@ -67,7 +76,7 @@ class Rivets.Binding
 
 
   # Publishes the value currently set on the input element back to the model.
   # Publishes the value currently set on the input element back to the model.
   publish: =>
   publish: =>
-    value = getInputValue @el
+    value = Rivets.Util.getInputValue @el
 
 
     for formatter in @formatters.slice(0).reverse()
     for formatter in @formatters.slice(0).reverse()
       args = formatter.split /\s+/
       args = formatter.split /\s+/
@@ -128,7 +137,10 @@ class Rivets.Binding
     @model = @view.models[@key]
     @model = @view.models[@key]
     @bind()
     @bind()
 
 
-# A collection of bindings built from a set of parent elements.
+# Rivets.View
+# -----------
+
+# A collection of bindings built from a set of parent nodes.
 class Rivets.View
 class Rivets.View
   # The DOM elements and the model objects for binding are passed into the
   # The DOM elements and the model objects for binding are passed into the
   # constructor along with any local options that should be used throughout the
   # constructor along with any local options that should be used throughout the
@@ -148,9 +160,9 @@ class Rivets.View
     prefix = @config.prefix
     prefix = @config.prefix
     if prefix then new RegExp("^data-#{prefix}-") else /^data-/
     if prefix then new RegExp("^data-#{prefix}-") else /^data-/
 
 
-  # Parses the DOM tree and builds Rivets.Binding instances for every matched
+  # Parses the DOM tree and builds `Rivets.Binding` instances for every matched
   # binding declaration. Subsequent calls to build will replace the previous
   # binding declaration. Subsequent calls to build will replace the previous
-  # Rivets.Binding instances with new ones, so be sure to unbind them first.
+  # `Rivets.Binding` instances with new ones, so be sure to unbind them first.
   build: =>
   build: =>
     @bindings = []
     @bindings = []
     skipNodes = []
     skipNodes = []
@@ -233,40 +245,39 @@ class Rivets.View
       @models[key] = model
       @models[key] = model
       binding.update() for binding in @select (b) -> b.key is key
       binding.update() for binding in @select (b) -> b.key is key
 
 
-# Cross-browser event binding.
-bindEvent = (el, event, handler, context) ->
+# Rivets.Util
+# -----------
+
+# Houses common utility functions used internally by Rivets.js.
+Rivets.Util =
+  # Create a single DOM event binding.
+  bindEvent: (el, event, handler, context) ->
     fn = (e) -> handler.call context, e
     fn = (e) -> handler.call context, e
 
 
-  # Check to see if jQuery is loaded.
     if window.jQuery?
     if window.jQuery?
       el = jQuery el
       el = jQuery el
       if el.on? then el.on event, fn else el.bind event, fn
       if el.on? then el.on event, fn else el.bind event, fn
-  # Check to see if addEventListener is available.
     else if window.addEventListener?
     else if window.addEventListener?
       el.addEventListener event, fn, false
       el.addEventListener event, fn, false
     else
     else
-    # Assume we are in IE and use attachEvent.
       event = 'on' + event
       event = 'on' + event
       el.attachEvent event, fn
       el.attachEvent event, fn
 
 
     fn
     fn
 
 
-# Cross-browser event unbinding.
-unbindEvent = (el, event, fn) ->
-  # Check to see if jQuery is loaded.
+  # Remove a single DOM event binding.
+  unbindEvent: (el, event, fn) ->
     if window.jQuery?
     if window.jQuery?
       el = jQuery el
       el = jQuery el
       if el.off? then el.off event, fn else el.unbind event, fn
       if el.off? then el.off event, fn else el.unbind event, fn
-  # Check to see if addEventListener is available.
     else if window.removeEventListener
     else if window.removeEventListener
       el.removeEventListener event, fn, false
       el.removeEventListener event, fn, false
     else
     else
-  # Assume we are in IE and use attachEvent.
       event = 'on' + event
       event = 'on' + event
       el.detachEvent  event, fn
       el.detachEvent  event, fn
 
 
-# Cross-browser input value getter.
-getInputValue = (el) ->
+  # Get the current value of an input node.
+  getInputValue: (el) ->
     if window.jQuery?
     if window.jQuery?
       el = jQuery el
       el = jQuery el
 
 
@@ -279,7 +290,12 @@ getInputValue = (el) ->
         when 'select-multiple' then o.value for o in el when o.selected
         when 'select-multiple' then o.value for o in el when o.selected
         else el.value
         else el.value
 
 
-# Core binding routines.
+# Rivets.binders
+# --------------
+
+# Core binders that are included with Rivets.js, publicly available on
+# `module.binders`. Can be overridden globally or local to a `Rivets.View`
+# instance.
 Rivets.binders =
 Rivets.binders =
   enabled: (el, value) ->
   enabled: (el, value) ->
     el.disabled = !value
     el.disabled = !value
@@ -290,9 +306,9 @@ Rivets.binders =
   checked:
   checked:
     publishes: true
     publishes: true
     bind: (el) ->
     bind: (el) ->
-      @currentListener = bindEvent el, 'change', @publish
+      @currentListener = Rivets.Util.bindEvent el, 'change', @publish
     unbind: (el) ->
     unbind: (el) ->
-      unbindEvent el, 'change', @currentListener
+      Rivets.Util.unbindEvent el, 'change', @currentListener
     routine: (el, value) ->
     routine: (el, value) ->
       if el.type is 'radio'
       if el.type is 'radio'
         el.checked = el.value?.toString() is value?.toString()
         el.checked = el.value?.toString() is value?.toString()
@@ -302,9 +318,9 @@ Rivets.binders =
   unchecked:
   unchecked:
     publishes: true
     publishes: true
     bind: (el) ->
     bind: (el) ->
-      @currentListener = bindEvent el, 'change', @publish
+      @currentListener = Rivets.Util.bindEvent el, 'change', @publish
     unbind: (el) ->
     unbind: (el) ->
-      unbindEvent el, 'change', @currentListener
+      Rivets.Util.unbindEvent el, 'change', @currentListener
     routine: (el, value) ->
     routine: (el, value) ->
       if el.type is 'radio'
       if el.type is 'radio'
         el.checked = el.value?.toString() isnt value?.toString()
         el.checked = el.value?.toString() isnt value?.toString()
@@ -323,9 +339,9 @@ Rivets.binders =
   value:
   value:
     publishes: true
     publishes: true
     bind: (el) ->
     bind: (el) ->
-      @currentListener = bindEvent el, 'change', @publish
+      @currentListener = Rivets.Util.bindEvent el, 'change', @publish
     unbind: (el) ->
     unbind: (el) ->
-      unbindEvent el, 'change', @currentListener
+      Rivets.Util.unbindEvent el, 'change', @currentListener
     routine: (el, value) ->
     routine: (el, value) ->
       if window.jQuery?
       if window.jQuery?
         el = jQuery el
         el = jQuery el
@@ -347,8 +363,8 @@ Rivets.binders =
   "on-*":
   "on-*":
     function: true
     function: true
     routine: (el, value) ->
     routine: (el, value) ->
-      unbindEvent el, @args[0], @currentListener if @currentListener
-      @currentListener = bindEvent el, @args[0], value, @model
+      Rivets.Util.unbindEvent el, @args[0], @currentListener if @currentListener
+      @currentListener = Rivets.Util.bindEvent el, @args[0], value, @model
 
 
   "each-*":
   "each-*":
     block: true
     block: true
@@ -400,15 +416,27 @@ Rivets.binders =
     else
     else
       el.removeAttribute @type
       el.removeAttribute @type
 
 
-# Default configuration.
+# Rivets.config
+# -------------
+
+# Default configuration, publicly accessible on `module.config`. Can be
+# overridden globally or local to a `Rivets.View` instance.
 Rivets.config =
 Rivets.config =
   preloadData: true
   preloadData: true
 
 
-# Default formatters. There aren't any.
+# Rivets.formatters
+# -----------------
+
+# Default formatters (there aren't any), publicly accessible on
+# `module.formatters`. Can be overridden globally or local to a `Rivets.View`
+# instance.
 Rivets.formatters = {}
 Rivets.formatters = {}
 
 
-# The rivets module. This is the public interface that gets exported.
-factory = (exports) ->
+# Rivets.factory
+# --------------
+
+# The Rivets.js module factory.
+Rivets.factory = (exports) ->
   # Exposes the core binding routines that can be extended or stripped down.
   # Exposes the core binding routines that can be extended or stripped down.
   exports.binders = Rivets.binders
   exports.binders = Rivets.binders
 
 
@@ -425,19 +453,22 @@ factory = (exports) ->
       Rivets.config[property] = value
       Rivets.config[property] = value
     return
     return
 
 
-  # Binds a set of model objects to a parent DOM element. Returns a Rivets.View
-  # instance.
+  # Binds a set of model objects to a parent DOM element and returns a
+  # `Rivets.View` instance.
   exports.bind = (el, models = {}, options = {}) ->
   exports.bind = (el, models = {}, options = {}) ->
     view = new Rivets.View(el, models, options)
     view = new Rivets.View(el, models, options)
     view.bind()
     view.bind()
     view
     view
 
 
-# Exports rivets for CommonJS, AMD and the browser.
+# Export
+# ------
+
+# Exports Rivets.js for CommonJS, AMD and the browser.
 if typeof exports == 'object'
 if typeof exports == 'object'
-  factory(exports)
+  Rivets.factory(exports)
 else if typeof define == 'function' && define.amd
 else if typeof define == 'function' && define.amd
   define ['exports'], (exports) ->
   define ['exports'], (exports) ->
-    factory(@rivets = exports)
+    Rivets.factory(@rivets = exports)
     return exports
     return exports
 else
 else
-  factory(@rivets = {})
+  Rivets.factory(@rivets = {})