 
     new Range.NormalizedRange(nr)
 
+  # Public: Creates a range suitable for storage.
+  #
+  # root           - A root Element from which to anchor the serialisation.
+  # ignoreSelector - A selector String of elements to ignore. For example
+  #                  elements injected by the annotator.
+  #
+  # Returns an instance of SerializedRange.
   serialize: (root, ignoreSelector) ->
     this.normalize(root).serialize(root, ignoreSelector)
 
+# Public: A normalised range is most commonly used throughout the annotator.
+# its the result of a deserialised SerializedRange or a BrowserRange with
+# out browser inconsistencies.
 class Range.NormalizedRange
 
+  # Public: Creates an instance of a NormalizedRange.
+  #
+  # This is usually created by calling the .normalize() method on one of the
+  # other Range classes rather than manually.
+  #
+  # obj - An Object literal. Should have the following properties.
+  #       commonAncestor: A Element that encompasses both the start and end nodes
+  #       start:          The first TextNode in the range.
+  #       end             The last TextNode in the range.
+  #
+  # Returns an instance of NormalizedRange.
   constructor: (obj) ->
     @commonAncestor = obj.commonAncestor
     @start          = obj.start
     @end            = obj.end
 
+  # Public: For API consistency.
+  #
+  # Returns itself.
   normalize: (root) ->
     this
 

    @endContainer            = obj.endContainer
    @endOffset               = obj.endOffset

  ##
  # normalize works around the fact that browsers don't generate
  # ranges/selections in a consistent manner. Some (Safari) will create
  # ranges that have (say) a textNode startContainer and elementNode
  # endContainer. Others (Firefox) seem to only ever generate
  # textNode/textNode or elementNode/elementNode pairs.
  #
  # This will return an instance of Range.NormalizedRange
  normalize: (root) ->
    if @tainted
      console.error("You may only call normalize() once on a BrowserRange!")

      endOffset: end[1]
    })

  # Public: Creates a concatenated String of the contents of all the text nodes
  # within the range.
  #
  # Returns a String.
  text: ->
    (for node in this.textNodes()
      node.nodeValue
    ).join ''

  # Public: Fetches only the text nodes within th range.
  #
  # Returns an Array of TextNode instances.
  textNodes: ->
    textNodes = $(this.commonAncestor).textNodes()
    [start, end] = [textNodes.index(this.start), textNodes.index(this.end)]
    # Return the textNodes that fall between the start and end indexes.
    $.makeArray textNodes[start..end]

# Public: A range suitable for storing in local storage or serializing to JSON.
class Range.SerializedRange

  # Public: Creates a SerializedRange
  #
  # obj - The stored object. It should have the following properties.
  #       start:       An xpath to the Element containing the first TextNode
  #                    relative to the root Element.
  #       startOffset: The offset to the start of the selection from obj.start.
  #       end:         An xpath to the Element containing the last TextNode
  #                    relative to the root Element.
  #       startOffset: The offset to the end of the selection from obj.end. 
  #
  # Returns an instance of SerializedRange
  constructor: (obj) ->
    @start       = obj.start
    @startOffset = obj.startOffset
    @end         = obj.end
    @endOffset   = obj.endOffset

  # Public: Creates a NormalizedRange.
  #
  # root - The root Element from which the XPaths were generated.
  #
  # Returns a NormalizedRange instance.
  normalize: (root) ->
    nodeFromXPath = (xpath) ->
      document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue
