         inherited: inherited
         tag: json.tag
     else
+            # Clear copied or inherited values.
       newClass.className = `undefined`
       newClass::inherited = null
     newClass
 
+  ###
+  An element may have been added to the document; see if it's a control that's
+  waiting to be notified of that via Control.prototype.inDocument().
+  ### 
   _checkForElementInsertion: (event) ->
     callbacksReady = []
     i = 0
     while i < Control._elementInsertionCallbacks.length
       element = Control._elementInsertionCallbacks[i].element
       if isElementInDocument(element)
+                # The element has been inserted into the document. Move it
+                # into the list of callbacks which we can now invoke.
         callbacksReady = callbacksReady.concat(Control._elementInsertionCallbacks[i])
+                # Now remove it from the pending list. We remove it from the list
+                # *beforewe invoke the callback -- because the callback
+                # itself might do DOM manipulations that trigger more DOM
+                # mutation events.
         Control._elementInsertionCallbacks.splice i, 1
       else
         i++
+            # No more elements to wait for.
     Control._stopListeningForElementInsertion()  if Control._elementInsertionCallbacks.length is 0
     i = 0
     while i < callbacksReady.length

      window.clearInterval Control._elementInsertionInterval
      Control._elementInsertionInterval = null

$.extend Control.property,
  bool: (sideEffectFn, defaultValue) ->
    Control.property sideEffectFn, defaultValue, convertToBool = (value) ->
      String(value) is "true"

  class: (sideEffectFn, defaultValue) ->
    Control.property sideEffectFn, defaultValue, Control.getClass

  date: (sideEffectFn, defaultValue) ->
    Control.property sideEffectFn, defaultValue, convertToDate = (value) ->
      (if (value instanceof Date or not value?) then value else new Date(Date.parse(value)))

  integer: (sideEffectFn, defaultValue) ->
    Control.property sideEffectFn, defaultValue, parseInt

  _symbolCounter: 0

$.extend Control::,
  applyClass: (classes, value) ->
    (if (value is `undefined`) then @hasClass(classes) else @toggleClass(classes, String(value) is "true"))

  cast: (defaultClass) ->
    defaultClass = defaultClass or @constructor
    setClass = undefined

        Control._startListeningForElementInsertion()  unless Control._listeningForElementInsertion
      this

  ###
  Return true if the (first) element is an input element (with a val).
  Note that buttons are not considered input elements, because typically
  when one is setting their contents, one wants to set their label, not
  their "value".
  ###
  isInputElement: ->
    inputTags = [ "input", "select", "textarea" ]
    (if @length is 0 then false else ($.inArray(this[0].nodeName.toLowerCase(), inputTags) >= 0))

  ###
  Apply the indicated JSON to the control. Each key in the JSON will
  invoke the corresponding setter function in a function chain. E.g.,
  the JSON dictionary
  
       {
           foo: "Hello",
           bar: "World"
       }
  
  will invoke this.foo("Hello").bar("World").
  
  If a dictionary value is itself a JSON object, it will be reconstituted
  into HTML, or controls, or an array.
  
  This is similar to properties(), but that function doesn't attempt any
  processing of the values.
  
  The logicalParent parameter is intended for internal use only.
  ###
  json: (json, logicalParent) ->
    logicalParent = logicalParent or this
    i = 0
