rexml 3.2.3 → 3.3.8

data/lib/rexml/element.rb

@@ -7,17 +7,267 @@ require_relative "xpath"
 require_relative "parseexception"
 
 module REXML
-  # An implementation note about namespaces:
-  # As we parse, when we find namespaces we put them in a hash and assign
-  # them a unique ID.  We then convert the namespace prefix for the node
-  # to the unique ID.  This makes namespace lookup much faster for the
-  # cost of extra memory use.  We save the namespace prefix for the
-  # context node and convert it back when we write it.
-  @@namespaces = {}
-
-  # Represents a tagged XML element.  Elements are characterized by
-  # having children, attributes, and names, and can themselves be
-  # children.
+  # An \REXML::Element object represents an XML element.
+  #
+  # An element:
+  #
+  # - Has a name (string).
+  # - May have a parent (another element).
+  # - Has zero or more children
+  #   (other elements, text, CDATA, processing instructions, and comments).
+  # - Has zero or more siblings
+  #   (other elements, text, CDATA, processing instructions, and comments).
+  # - Has zero or more named attributes.
+  #
+  # == In a Hurry?
+  #
+  # If you're somewhat familiar with XML
+  # and have a particular task in mind,
+  # you may want to see the
+  # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html],
+  # and in particular, the
+  # {tasks page for elements}[../doc/rexml/tasks/tocs/element_toc_rdoc.html].
+  #
+  # === Name
+  #
+  # An element has a name, which is initially set when the element is created:
+  #
+  #   e = REXML::Element.new('foo')
+  #   e.name # => "foo"
+  #
+  # The name may be changed:
+  #
+  #   e.name = 'bar'
+  #   e.name # => "bar"
+  #
+  #
+  # === \Parent
+  #
+  # An element may have a parent.
+  #
+  # Its parent may be assigned explicitly when the element is created:
+  #
+  #   e0 = REXML::Element.new('foo')
+  #   e1 = REXML::Element.new('bar', e0)
+  #   e1.parent # => <foo> ... </>
+  #
+  # Note: the representation of an element always shows the element's name.
+  # If the element has children, the representation indicates that
+  # by including an ellipsis (<tt>...</tt>).
+  #
+  # The parent may be assigned explicitly at any time:
+  #
+  #   e2 = REXML::Element.new('baz')
+  #   e1.parent = e2
+  #   e1.parent # => <baz/>
+  #
+  # When an element is added as a child, its parent is set automatically:
+  #
+  #   e1.add_element(e0)
+  #   e0.parent # => <bar> ... </>
+  #
+  # For an element that has no parent, method +parent+ returns +nil+.
+  #
+  # === Children
+  #
+  # An element has zero or more children.
+  # The children are an ordered collection
+  # of all objects whose parent is the element itself.
+  #
+  # The children may include any combination of elements, text, comments,
+  # processing instructions, and CDATA.
+  # (This example keeps things clean by controlling whitespace
+  # via a +context+ setting.)
+  #
+  #    xml_string = <<-EOT
+  #    <root>
+  #      <ele_0/>
+  #      text 0
+  #      <!--comment 0-->
+  #      <?target_0 pi_0?>
+  #      <![CDATA[cdata 0]]>
+  #      <ele_1/>
+  #      text 1
+  #      <!--comment 1-->
+  #      <?target_0 pi_1?>
+  #      <![CDATA[cdata 1]]>
+  #    </root>
+  #    EOT
+  #    context = {ignore_whitespace_nodes: :all, compress_whitespace: :all}
+  #    d = REXML::Document.new(xml_string, context)
+  #    root = d.root
+  #    root.children.size # => 10
+  #    root.each {|child| p "#{child.class}: #{child}" }
+  #
+  # Output:
+  #
+  #   "REXML::Element: <ele_0/>"
+  #   "REXML::Text: \n text 0\n "
+  #   "REXML::Comment: comment 0"
+  #   "REXML::Instruction: <?target_0 pi_0?>"
+  #   "REXML::CData: cdata 0"
+  #   "REXML::Element: <ele_1/>"
+  #   "REXML::Text: \n text 1\n "
+  #   "REXML::Comment: comment 1"
+  #   "REXML::Instruction: <?target_0 pi_1?>"
+  #   "REXML::CData: cdata 1"
+  #
+  # A child may be added using inherited methods
+  # Parent#insert_before or Parent#insert_after:
+  #
+  #   xml_string = '<root><a/><c/><d/></root>'
+  #   d = REXML::Document.new(xml_string)
+  #   root = d.root
+  #   c = d.root[1] # => <c/>
+  #   root.insert_before(c, REXML::Element.new('b'))
+  #   root.to_a # => [<a/>, <b/>, <c/>, <d/>]
+  #
+  # A child may be replaced using Parent#replace_child:
+  #
+  #   root.replace_child(c, REXML::Element.new('x'))
+  #   root.to_a # => [<a/>, <b/>, <x/>, <d/>]
+  #
+  # A child may be removed using Parent#delete:
+  #
+  #   x = root[2] # => <x/>
+  #   root.delete(x)
+  #   root.to_a # => [<a/>, <b/>, <d/>]
+  #
+  # === Siblings
+  #
+  # An element has zero or more siblings,
+  # which are the other children of the element's parent.
+  #
+  # In the example above, element +ele_1+ is between a CDATA sibling
+  # and a text sibling:
+  #
+  #   ele_1 = root[5]        # => <ele_1/>
+  #   ele_1.previous_sibling # => "cdata 0"
+  #   ele_1.next_sibling     # => "\n text 1\n "
+  #
+  # === \Attributes
+  #
+  # An element has zero or more named attributes.
+  #
+  # A new element has no attributes:
+  #
+  #   e = REXML::Element.new('foo')
+  #   e.attributes      # => {}
+  #
+  # Attributes may be added:
+  #
+  #   e.add_attribute('bar', 'baz')
+  #   e.add_attribute('bat', 'bam')
+  #   e.attributes.size # => 2
+  #   e['bar']          # => "baz"
+  #   e['bat']          # => "bam"
+  #
+  # An existing attribute may be modified:
+  #
+  #   e.add_attribute('bar', 'bad')
+  #   e.attributes.size # => 2
+  #   e['bar']          # => "bad"
+  #
+  # An existing attribute may be deleted:
+  #
+  #   e.delete_attribute('bar')
+  #   e.attributes.size # => 1
+  #   e['bar']          # => nil
+  #
+  # == What's Here
+  #
+  # To begin with, what's elsewhere?
+  #
+  # \Class \REXML::Element inherits from its ancestor classes:
+  #
+  # - REXML::Child
+  # - REXML::Parent
+  #
+  # \REXML::Element itself and its ancestors also include modules:
+  #
+  # - {Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html]
+  # - REXML::Namespace
+  # - REXML::Node
+  # - REXML::XMLTokens
+  #
+  # === Methods for Creating an \Element
+  #
+  # ::new:: Returns a new empty element.
+  # #clone:: Returns a clone of another element.
+  #
+  # === Methods for Attributes
+  #
+  # {[attribute_name]}[#method-i-5B-5D]:: Returns an attribute value.
+  # #add_attribute:: Adds a new attribute.
+  # #add_attributes:: Adds multiple new attributes.
+  # #attribute:: Returns the attribute value for a given name and optional namespace.
+  # #delete_attribute:: Removes an attribute.
+  #
+  # === Methods for Children
+  #
+  # {[index]}[#method-i-5B-5D]:: Returns the child at the given offset.
+  # #add_element:: Adds an element as the last child.
+  # #delete_element:: Deletes a child element.
+  # #each_element:: Calls the given block with each child element.
+  # #each_element_with_attribute:: Calls the given block with each child element
+  #                                that meets given criteria,
+  #                                which can include the attribute name.
+  # #each_element_with_text:: Calls the given block with each child element
+  #                           that meets given criteria,
+  #                           which can include text.
+  # #get_elements:: Returns an array of element children that match a given xpath.
+  #
+  # === Methods for \Text Children
+  #
+  # #add_text:: Adds a text node to the element.
+  # #get_text:: Returns a text node that meets specified criteria.
+  # #text:: Returns the text string from the first node that meets specified criteria.
+  # #texts:: Returns an array of the text children of the element.
+  # #text=:: Adds, removes, or replaces the first text child of the element
+  #
+  # === Methods for Other Children
+  #
+  # #cdatas:: Returns an array of the cdata children of the element.
+  # #comments:: Returns an array of the comment children of the element.
+  # #instructions:: Returns an array of the instruction children of the element.
+  #
+  # === Methods for Namespaces
+  #
+  # #add_namespace:: Adds a namespace to the element.
+  # #delete_namespace:: Removes a namespace from the element.
+  # #namespace:: Returns the string namespace URI for the element.
+  # #namespaces:: Returns a hash of all defined namespaces in the element.
+  # #prefixes:: Returns an array of the string prefixes (names)
+  #             of all defined namespaces in the element
+  #
+  # === Methods for Querying
+  #
+  # #document:: Returns the document, if any, that the element belongs to.
+  # #root:: Returns the most distant element (not document) ancestor of the element.
+  # #root_node:: Returns the most distant ancestor of the element.
+  # #xpath:: Returns the string xpath to the element
+  #          relative to the most distant parent
+  # #has_attributes?:: Returns whether the element has attributes.
+  # #has_elements?:: Returns whether the element has elements.
+  # #has_text?:: Returns whether the element has text.
+  # #next_element:: Returns the next sibling that is an element.
+  # #previous_element:: Returns the previous sibling that is an element.
+  # #raw:: Returns whether raw mode is set for the element.
+  # #whitespace:: Returns whether whitespace is respected for the element.
+  # #ignore_whitespace_nodes:: Returns whether whitespace nodes
+  #                            are to be ignored for the element.
+  # #node_type:: Returns symbol <tt>:element</tt>.
+  #
+  # === One More Method
+  #
+  # #inspect:: Returns a string representation of the element.
+  #
+  # === Accessors
+  #
+  # #elements:: Returns the REXML::Elements object for the element.
+  # #attributes:: Returns the REXML::Attributes object for the element.
+  # #context:: Returns or sets the context hash for the element.
+  #
   class Element < Parent
     include Namespace
 
@@ -30,32 +280,42 @@ module REXML
     # whitespace handling.
     attr_accessor :context
 
-    # Constructor
-    # arg::
-    #   if not supplied, will be set to the default value.
-    #   If a String, the name of this object will be set to the argument.
-    #   If an Element, the object will be shallowly cloned; name,
-    #   attributes, and namespaces will be copied.  Children will +not+ be
-    #   copied.
-    # parent::
-    #   if supplied, must be a Parent, and will be used as
-    #   the parent of this object.
-    # context::
-    #   If supplied, must be a hash containing context items.  Context items
-    #   include:
-    # * <tt>:respect_whitespace</tt> the value of this is :+all+ or an array of
-    #   strings being the names of the elements to respect
-    #   whitespace for.  Defaults to :+all+.
-    # * <tt>:compress_whitespace</tt> the value can be :+all+ or an array of
-    #   strings being the names of the elements to ignore whitespace on.
-    #   Overrides :+respect_whitespace+.
-    # * <tt>:ignore_whitespace_nodes</tt> the value can be :+all+ or an array
-    #   of strings being the names of the elements in which to ignore
-    #   whitespace-only nodes.  If this is set, Text nodes which contain only
-    #   whitespace will not be added to the document tree.
-    # * <tt>:raw</tt> can be :+all+, or an array of strings being the names of
-    #   the elements to process in raw mode.  In raw mode, special
-    #   characters in text is not converted to or from entities.
+    # :call-seq:
+    #   Element.new(name = 'UNDEFINED', parent = nil, context = nil) -> new_element
+    #   Element.new(element, parent = nil, context = nil) -> new_element
+    #
+    # Returns a new \REXML::Element object.
+    #
+    # When no arguments are given,
+    # returns an element with name <tt>'UNDEFINED'</tt>:
+    #
+    #   e = REXML::Element.new # => <UNDEFINED/>
+    #   e.class                # => REXML::Element
+    #   e.name                 # => "UNDEFINED"
+    #
+    # When only argument +name+ is given,
+    # returns an element of the given name:
+    #
+    #   REXML::Element.new('foo') # => <foo/>
+    #
+    # When only argument +element+ is given, it must be an \REXML::Element object;
+    # returns a shallow copy of the given element:
+    #
+    #   e0 = REXML::Element.new('foo')
+    #   e1 = REXML::Element.new(e0) # => <foo/>
+    #
+    # When argument +parent+ is also given, it must be an REXML::Parent object:
+    #
+    #   e = REXML::Element.new('foo', REXML::Parent.new)
+    #   e.parent # => #<REXML::Parent @parent=nil, @children=[<foo/>]>
+    #
+    # When argument +context+ is also given, it must be a hash
+    # representing the context for the element;
+    # see {Element Context}[../doc/rexml/context_rdoc.html]:
+    #
+    #   e = REXML::Element.new('foo', nil, {raw: :all})
+    #   e.context # => {:raw=>:all}
+    #
     def initialize( arg = UNDEFINED, parent=nil, context=nil )
       super(parent)
 
@@ -74,6 +334,27 @@ module REXML
       end
     end
 
+    # :call-seq:
+    #   inspect -> string
+    #
+    # Returns a string representation of the element.
+    #
+    # For an element with no attributes and no children, shows the element name:
+    #
+    #   REXML::Element.new.inspect # => "<UNDEFINED/>"
+    #
+    # Shows attributes, if any:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.add_attributes({'bar' => 0, 'baz' => 1})
+    #   e.inspect # => "<foo bar='0' baz='1'/>"
+    #
+    # Shows an ellipsis (<tt>...</tt>), if there are child elements:
+    #
+    #   e.add_element(REXML::Element.new('bar'))
+    #   e.add_element(REXML::Element.new('baz'))
+    #   e.inspect # => "<foo bar='0' baz='1'> ... </>"
+    #
     def inspect
       rv = "<#@expanded_name"
 
@@ -89,60 +370,123 @@ module REXML
       end
     end
 
-
-    # Creates a shallow copy of self.
-    #   d = Document.new "<a><b/><b/><c><d/></c></a>"
-    #   new_a = d.root.clone
-    #   puts new_a  # => "<a/>"
+    # :call-seq:
+    #   clone -> new_element
+    #
+    # Returns a shallow copy of the element, containing the name and attributes,
+    # but not the parent or children:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.add_attributes({'bar' => 0, 'baz' => 1})
+    #   e.clone # => <foo bar='0' baz='1'/>
+    #
     def clone
       self.class.new self
     end
 
-    # Evaluates to the root node of the document that this element
-    # belongs to. If this element doesn't belong to a document, but does
-    # belong to another Element, the parent's root will be returned, until the
-    # earliest ancestor is found.
-    #
-    # Note that this is not the same as the document element.
-    # In the following example, <a> is the document element, and the root
-    # node is the parent node of the document element.  You may ask yourself
-    # why the root node is useful: consider the doctype and XML declaration,
-    # and any processing instructions before the document element... they
-    # are children of the root node, or siblings of the document element.
-    # The only time this isn't true is when an Element is created that is
-    # not part of any Document.  In this case, the ancestor that has no
-    # parent acts as the root node.
-    #  d = Document.new '<a><b><c/></b></a>'
-    #  a = d[1] ; c = a[1][1]
-    #  d.root_node == d   # TRUE
-    #  a.root_node        # namely, d
-    #  c.root_node        # again, d
+    # :call-seq:
+    #   root_node -> document or element
+    #
+    # Returns the most distant ancestor of +self+.
+    #
+    # When the element is part of a document,
+    # returns the root node of the document.
+    # Note that the root node is different from the document element;
+    # in this example +a+ is document element and the root node is its parent:
+    #
+    #   d = REXML::Document.new('<a><b><c/></b></a>')
+    #   top_element = d.first      # => <a> ... </>
+    #   child = top_element.first  # => <b> ... </>
+    #   d.root_node == d           # => true
+    #   top_element.root_node == d # => true
+    #   child.root_node == d       # => true
+    #
+    # When the element is not part of a document, but does have ancestor elements,
+    # returns the most distant ancestor element:
+    #
+    #   e0 = REXML::Element.new('foo')
+    #   e1 = REXML::Element.new('bar')
+    #   e1.parent = e0
+    #   e2 = REXML::Element.new('baz')
+    #   e2.parent = e1
+    #   e2.root_node == e0 # => true
+    #
+    # When the element has no ancestor elements,
+    # returns +self+:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.root_node == e # => true
+    #
+    # Related: #root, #document.
+    #
     def root_node
       parent.nil? ? self : parent.root_node
     end
 
+    # :call-seq:
+    #   root -> element
+    #
+    # Returns the most distant _element_ (not document) ancestor of the element:
+    #
+    #   d = REXML::Document.new('<a><b><c/></b></a>')
+    #   top_element = d.first
+    #   child = top_element.first
+    #   top_element.root == top_element # => true
+    #   child.root == top_element       # => true
+    #
+    # For a document, returns the topmost element:
+    #
+    #   d.root == top_element # => true
+    #
+    # Related: #root_node, #document.
+    #
     def root
-      return elements[1] if self.kind_of? Document
-      return self if parent.kind_of? Document or parent.nil?
-      return parent.root
+      target = self
+      while target
+        return target.elements[1] if target.kind_of? Document
+        parent = target.parent
+        return target if parent.kind_of? Document or parent.nil?
+        target = parent
+      end
+      nil
     end
 
-    # Evaluates to the document to which this element belongs, or nil if this
-    # element doesn't belong to a document.
+    # :call-seq:
+    #   document -> document or nil
+    #
+    # If the element is part of a document, returns that document:
+    #
+    #   d = REXML::Document.new('<a><b><c/></b></a>')
+    #   top_element = d.first
+    #   child = top_element.first
+    #   top_element.document == d # => true
+    #   child.document == d       # => true
+    #
+    # If the element is not part of a document, returns +nil+:
+    #
+    #   REXML::Element.new.document # => nil
+    #
+    # For a document, returns +self+:
+    #
+    #   d.document == d           # => true
+    #
+    # Related: #root, #root_node.
+    #
     def document
       rt = root
       rt.parent if rt
     end
 
-    # Evaluates to +true+ if whitespace is respected for this element.  This
-    # is the case if:
-    # 1. Neither :+respect_whitespace+ nor :+compress_whitespace+ has any value
-    # 2. The context has :+respect_whitespace+ set to :+all+ or
-    #    an array containing the name of this element, and
-    #    :+compress_whitespace+ isn't set to :+all+ or an array containing the
-    #    name of this element.
-    # The evaluation is tested against +expanded_name+, and so is namespace
-    # sensitive.
+    # :call-seq:
+    #   whitespace
+    #
+    # Returns +true+ if whitespace is respected for this element,
+    # +false+ otherwise.
+    #
+    # See {Element Context}[../doc/rexml/context_rdoc.html].
+    #
+    # The evaluation is tested against the element's +expanded_name+,
+    # and so is namespace-sensitive.
     def whitespace
       @whitespace = nil
       if @context
@@ -159,6 +503,13 @@ module REXML
       @whitespace
     end
 
+    # :call-seq:
+    #   ignore_whitespace_nodes
+    #
+    # Returns +true+ if whitespace nodes are ignored for the element.
+    #
+    # See {Element Context}[../doc/rexml/context_rdoc.html].
+    #
     def ignore_whitespace_nodes
       @ignore_whitespace_nodes = false
       if @context
@@ -170,9 +521,12 @@ module REXML
       end
     end
 
-    # Evaluates to +true+ if raw mode is set for this element.  This
-    # is the case if the context has :+raw+ set to :+all+ or
-    # an array containing the name of this element.
+    # :call-seq:
+    #   raw
+    #
+    # Returns +true+ if raw mode is set for the element.
+    #
+    # See {Element Context}[../doc/rexml/context_rdoc.html].
     #
     # The evaluation is tested against +expanded_name+, and so is namespace
     # sensitive.
@@ -180,7 +534,7 @@ module REXML
       @raw = (@context and @context[:raw] and
               (@context[:raw] == :all or
                @context[:raw].include? expanded_name))
-               @raw
+      @raw
     end
 
     #once :whitespace, :raw, :ignore_whitespace_nodes
@@ -189,10 +543,25 @@ module REXML
     # Namespaces                                    #
     #################################################
 
-    # Evaluates to an +Array+ containing the prefixes (names) of all defined
-    # namespaces at this context node.
-    #  doc = Document.new("<a xmlns:x='1' xmlns:y='2'><b/><c xmlns:z='3'/></a>")
-    #  doc.elements['//b'].prefixes # -> ['x', 'y']
+    # :call-seq:
+    #   prefixes -> array_of_namespace_prefixes
+    #
+    # Returns an array of the string prefixes (names) of all defined namespaces
+    # in the element and its ancestors:
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #        <a xmlns:x='1' xmlns:y='2'>
+    #          <b/>
+    #          <c xmlns:z='3'/>
+    #        </a>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string, {compress_whitespace: :all})
+    #   d.elements['//a'].prefixes # => ["x", "y"]
+    #   d.elements['//b'].prefixes # => ["x", "y"]
+    #   d.elements['//c'].prefixes # => ["x", "y", "z"]
+    #
     def prefixes
       prefixes = []
       prefixes = parent.prefixes if parent
@@ -200,6 +569,25 @@ module REXML
       return prefixes
     end
 
+    # :call-seq:
+    #    namespaces -> array_of_namespace_names
+    #
+    # Returns a hash of all defined namespaces
+    # in the element and its ancestors:
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #        <a xmlns:x='1' xmlns:y='2'>
+    #          <b/>
+    #          <c xmlns:z='3'/>
+    #        </a>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   d.elements['//a'].namespaces # => {"x"=>"1", "y"=>"2"}
+    #   d.elements['//b'].namespaces # => {"x"=>"1", "y"=>"2"}
+    #   d.elements['//c'].namespaces # => {"x"=>"1", "y"=>"2", "z"=>"3"}
+    #
     def namespaces
       namespaces = {}
       namespaces = parent.namespaces if parent
@@ -207,19 +595,26 @@ module REXML
       return namespaces
     end
 
-    # Evaluates to the URI for a prefix, or the empty string if no such
-    # namespace is declared for this element. Evaluates recursively for
-    # ancestors.  Returns the default namespace, if there is one.
-    # prefix::
-    #   the prefix to search for.  If not supplied, returns the default
-    #   namespace if one exists
-    # Returns::
-    #   the namespace URI as a String, or nil if no such namespace
-    #   exists.  If the namespace is undefined, returns an empty string
-    #  doc = Document.new("<a xmlns='1' xmlns:y='2'><b/><c xmlns:z='3'/></a>")
-    #  b = doc.elements['//b']
-    #  b.namespace           # -> '1'
-    #  b.namespace("y")      # -> '2'
+    # :call-seq:
+    #   namespace(prefix = nil) -> string_uri or nil
+    #
+    # Returns the string namespace URI for the element,
+    # possibly deriving from one of its ancestors.
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #        <a xmlns='1' xmlns:y='2'>
+    #          <b/>
+    #          <c xmlns:z='3'/>
+    #        </a>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   b = d.elements['//b']
+    #   b.namespace      # => "1"
+    #   b.namespace('y') # => "2"
+    #   b.namespace('nosuch') # => nil
+    #
     def namespace(prefix=nil)
       if prefix.nil?
         prefix = prefix()
@@ -229,25 +624,34 @@ module REXML
       else
         prefix = "xmlns:#{prefix}" unless prefix[0,5] == 'xmlns'
       end
-      ns = attributes[ prefix ]
-      ns = parent.namespace(prefix) if ns.nil? and parent
+      ns = nil
+      target = self
+      while ns.nil? and target
+        ns = target.attributes[prefix]
+        target = target.parent
+      end
       ns = '' if ns.nil? and prefix == 'xmlns'
       return ns
     end
 
-    # Adds a namespace to this element.
-    # prefix::
-    #   the prefix string, or the namespace URI if +uri+ is not
-    #   supplied
-    # uri::
-    #   the namespace URI.  May be nil, in which +prefix+ is used as
-    #   the URI
-    # Evaluates to: this Element
-    #  a = Element.new("a")
-    #  a.add_namespace("xmlns:foo", "bar" )
-    #  a.add_namespace("foo", "bar")  # shorthand for previous line
-    #  a.add_namespace("twiddle")
-    #  puts a   #-> <a xmlns:foo='bar' xmlns='twiddle'/>
+    # :call-seq:
+    #   add_namespace(prefix, uri = nil) -> self
+    #
+    # Adds a namespace to the element; returns +self+.
+    #
+    # With the single argument +prefix+,
+    # adds a namespace using the given +prefix+ and the namespace URI:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.add_namespace('bar')
+    #   e.namespaces # => {"xmlns"=>"bar"}
+    #
+    # With both arguments +prefix+ and +uri+ given,
+    # adds a namespace using both arguments:
+    #
+    #   e.add_namespace('baz', 'bat')
+    #   e.namespaces # => {"xmlns"=>"bar", "baz"=>"bat"}
+    #
     def add_namespace( prefix, uri=nil )
       unless uri
         @attributes["xmlns"] = prefix
@@ -258,16 +662,28 @@ module REXML
       self
     end
 
-    # Removes a namespace from this node.  This only works if the namespace is
-    # actually declared in this node.  If no argument is passed, deletes the
-    # default namespace.
+    # :call-seq:
+    #   delete_namespace(namespace = 'xmlns') -> self
+    #
+    # Removes a namespace from the element.
+    #
+    # With no argument, removes the default namespace:
+    #
+    #   d = REXML::Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>"
+    #   d.to_s # => "<a xmlns:foo='bar' xmlns='twiddle'/>"
+    #   d.root.delete_namespace # => <a xmlns:foo='bar'/>
+    #   d.to_s # => "<a xmlns:foo='bar'/>"
+    #
+    # With argument +namespace+, removes the specified namespace:
+    #
+    #   d.root.delete_namespace('foo')
+    #   d.to_s # => "<a/>"
+    #
+    # Does nothing if no such namespace is found:
+    #
+    #   d.root.delete_namespace('nosuch')
+    #   d.to_s # => "<a/>"
     #
-    # Evaluates to: this element
-    #  doc = Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>"
-    #  doc.root.delete_namespace
-    #  puts doc     # -> <a xmlns:foo='bar'/>
-    #  doc.root.delete_namespace 'foo'
-    #  puts doc     # -> <a/>
     def delete_namespace namespace="xmlns"
       namespace = "xmlns:#{namespace}" unless namespace == 'xmlns'
       attribute = attributes.get_attribute(namespace)
@@ -279,20 +695,40 @@ module REXML
     # Elements                                      #
     #################################################
 
-    # Adds a child to this element, optionally setting attributes in
-    # the element.
-    # element::
-    #   optional.  If Element, the element is added.
-    #   Otherwise, a new Element is constructed with the argument (see
-    #   Element.initialize).
-    # attrs::
-    #   If supplied, must be a Hash containing String name,value
-    #   pairs, which will be used to set the attributes of the new Element.
-    # Returns:: the Element that was added
-    #  el = doc.add_element 'my-tag'
-    #  el = doc.add_element 'my-tag', {'attr1'=>'val1', 'attr2'=>'val2'}
-    #  el = Element.new 'my-tag'
-    #  doc.add_element el
+    # :call-seq:
+    #   add_element(name, attributes = nil) -> new_element
+    #   add_element(element, attributes = nil) -> element
+    #
+    # Adds a child element, optionally setting attributes
+    # on the added element; returns the added element.
+    #
+    # With string argument +name+, creates a new element with that name
+    # and adds the new element as a child:
+    #
+    #   e0 = REXML::Element.new('foo')
+    #   e0.add_element('bar')
+    #   e0[0] # => <bar/>
+    #
+    #
+    # With argument +name+ and hash argument +attributes+,
+    # sets attributes on the new element:
+    #
+    #   e0.add_element('baz', {'bat' => '0', 'bam' => '1'})
+    #   e0[1] # => <baz bat='0' bam='1'/>
+    #
+    # With element argument +element+, adds that element as a child:
+    #
+    #   e0 = REXML::Element.new('foo')
+    #   e1 = REXML::Element.new('bar')
+    #   e0.add_element(e1)
+    #   e0[0] # => <bar/>
+    #
+    # With argument +element+ and hash argument +attributes+,
+    # sets attributes on the added element:
+    #
+    #   e0.add_element(e1, {'bat' => '0', 'bam' => '1'})
+    #   e0[1] # => <bar bat='0' bam='1'/>
+    #
     def add_element element, attrs=nil
       raise "First argument must be either an element name, or an Element object" if element.nil?
       el = @elements.add(element)
@@ -302,52 +738,112 @@ module REXML
       el
     end
 
+    # :call-seq:
+    #   delete_element(index) -> removed_element or nil
+    #   delete_element(element) -> removed_element or nil
+    #   delete_element(xpath) -> removed_element or nil
+    #
     # Deletes a child element.
-    # element::
-    #   Must be an +Element+, +String+, or +Integer+.  If Element,
-    #   the element is removed.  If String, the element is found (via XPath)
-    #   and removed.  <em>This means that any parent can remove any
-    #   descendant.<em>  If Integer, the Element indexed by that number will be
-    #   removed.
-    # Returns:: the element that was removed.
-    #  doc.delete_element "/a/b/c[@id='4']"
-    #  doc.delete_element doc.elements["//k"]
-    #  doc.delete_element 1
+    #
+    # When 1-based integer argument +index+ is given,
+    # removes and returns the child element at that offset if it exists;
+    # indexing does not include text nodes;
+    # returns +nil+ if the element does not exist:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   a = d.root          # => <a> ... </>
+    #   a.delete_element(1) # => <b/>
+    #   a.delete_element(1) # => <c/>
+    #   a.delete_element(1) # => nil
+    #
+    # When element argument +element+ is given,
+    # removes and returns that child element if it exists,
+    # otherwise returns +nil+:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   a = d.root          # => <a> ... </>
+    #   c = a[2]            # => <c/>
+    #   a.delete_element(c) # => <c/>
+    #   a.delete_element(c) # => nil
+    #
+    # When xpath argument +xpath+ is given,
+    # removes and returns the element at xpath if it exists,
+    # otherwise returns +nil+:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   a = d.root              # => <a> ... </>
+    #   a.delete_element('//c') # => <c/>
+    #   a.delete_element('//c') # => nil
+    #
     def delete_element element
       @elements.delete element
     end
 
-    # Evaluates to +true+ if this element has at least one child Element
-    #  doc = Document.new "<a><b/><c>Text</c></a>"
-    #  doc.root.has_elements               # -> true
-    #  doc.elements["/a/b"].has_elements   # -> false
-    #  doc.elements["/a/c"].has_elements   # -> false
+    # :call-seq:
+    #   has_elements?
+    #
+    # Returns +true+ if the element has one or more element children,
+    # +false+ otherwise:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   a = d.root              # => <a> ... </>
+    #   a.has_elements? # => true
+    #   b = a[0]        # => <b/>
+    #   b.has_elements? # => false
+    #
     def has_elements?
       !@elements.empty?
     end
 
-    # Iterates through the child elements, yielding for each Element that
-    # has a particular attribute set.
-    # key::
-    #   the name of the attribute to search for
-    # value::
-    #   the value of the attribute
-    # max::
-    #   (optional) causes this method to return after yielding
-    #   for this number of matching children
-    # name::
-    #   (optional) if supplied, this is an XPath that filters
-    #   the children to check.
-    #
-    #  doc = Document.new "<a><b @id='1'/><c @id='2'/><d @id='1'/><e/></a>"
-    #  # Yields b, c, d
-    #  doc.root.each_element_with_attribute( 'id' ) {|e| p e}
-    #  # Yields b, d
-    #  doc.root.each_element_with_attribute( 'id', '1' ) {|e| p e}
-    #  # Yields b
-    #  doc.root.each_element_with_attribute( 'id', '1', 1 ) {|e| p e}
-    #  # Yields d
-    #  doc.root.each_element_with_attribute( 'id', '1', 0, 'd' ) {|e| p e}
+    # :call-seq:
+    #   each_element_with_attribute(attr_name, value = nil, max = 0, xpath = nil) {|e| ... }
+    #
+    # Calls the given block with each child element that meets given criteria.
+    #
+    # When only string argument +attr_name+ is given,
+    # calls the block with each child element that has that attribute:
+    #
+    #   d = REXML::Document.new '<a><b id="1"/><c id="2"/><d id="1"/><e/></a>'
+    #   a = d.root
+    #   a.each_element_with_attribute('id') {|e| p e }
+    #
+    # Output:
+    #
+    #   <b id='1'/>
+    #   <c id='2'/>
+    #   <d id='1'/>
+    #
+    # With argument +attr_name+ and string argument +value+ given,
+    # calls the block with each child element that has that attribute
+    # with that value:
+    #
+    #   a.each_element_with_attribute('id', '1') {|e| p e }
+    #
+    # Output:
+    #
+    #   <b id='1'/>
+    #   <d id='1'/>
+    #
+    # With arguments +attr_name+, +value+, and integer argument +max+ given,
+    # calls the block with at most +max+ child elements:
+    #
+    #   a.each_element_with_attribute('id', '1', 1) {|e| p e }
+    #
+    # Output:
+    #
+    #   <b id='1'/>
+    #
+    # With all arguments given, including +xpath+,
+    # calls the block with only those child elements
+    # that meet the first three criteria,
+    # and also match the given +xpath+:
+    #
+    #   a.each_element_with_attribute('id', '1', 2, '//d') {|e| p e }
+    #
+    # Output:
+    #
+    #   <d id='1'/>
+    #
     def each_element_with_attribute( key, value=nil, max=0, name=nil, &block ) # :yields: Element
       each_with_something( proc {|child|
         if value.nil?
@@ -358,27 +854,53 @@ module REXML
       }, max, name, &block )
     end
 
-    # Iterates through the children, yielding for each Element that
-    # has a particular text set.
-    # text::
-    #   the text to search for.  If nil, or not supplied, will iterate
-    #   over all +Element+ children that contain at least one +Text+ node.
-    # max::
-    #   (optional) causes this method to return after yielding
-    #   for this number of matching children
-    # name::
-    #   (optional) if supplied, this is an XPath that filters
-    #   the children to check.
-    #
-    #  doc = Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>'
-    #  # Yields b, c, d
-    #  doc.each_element_with_text {|e|p e}
-    #  # Yields b, c
-    #  doc.each_element_with_text('b'){|e|p e}
-    #  # Yields b
-    #  doc.each_element_with_text('b', 1){|e|p e}
-    #  # Yields d
-    #  doc.each_element_with_text(nil, 0, 'd'){|e|p e}
+    # :call-seq:
+    #   each_element_with_text(text = nil, max = 0, xpath = nil) {|e| ... }
+    #
+    # Calls the given block with each child element that meets given criteria.
+    #
+    # With no arguments, calls the block with each child element that has text:
+    #
+    #   d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>'
+    #   a = d.root
+    #   a.each_element_with_text {|e| p e }
+    #
+    # Output:
+    #
+    #   <b> ... </>
+    #   <c> ... </>
+    #   <d> ... </>
+    #
+    # With the single string argument +text+,
+    # calls the block with each element that has exactly that text:
+    #
+    #   a.each_element_with_text('b') {|e| p e }
+    #
+    # Output:
+    #
+    #   <b> ... </>
+    #   <c> ... </>
+    #
+    # With argument +text+ and integer argument +max+,
+    # calls the block with at most +max+ elements:
+    #
+    #   a.each_element_with_text('b', 1) {|e| p e }
+    #
+    # Output:
+    #
+    #   <b> ... </>
+    #
+    # With all arguments given, including +xpath+,
+    # calls the block with only those child elements
+    # that meet the first two criteria,
+    # and also match the given +xpath+:
+    #
+    #   a.each_element_with_text('b', 2, '//c') {|e| p e }
+    #
+    # Output:
+    #
+    #   <c> ... </>
+    #
     def each_element_with_text( text=nil, max=0, name=nil, &block ) # :yields: Element
       each_with_something( proc {|child|
         if text.nil?
@@ -389,35 +911,71 @@ module REXML
       }, max, name, &block )
     end
 
-    # Synonym for Element.elements.each
+    # :call-seq:
+    #   each_element {|e| ... }
+    #
+    # Calls the given block with each child element:
+    #
+    #   d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>'
+    #   a = d.root
+    #   a.each_element {|e| p e }
+    #
+    # Output:
+    #
+    #   <b> ... </>
+    #   <c> ... </>
+    #   <d> ... </>
+    #   <e/>
+    #
     def each_element( xpath=nil, &block ) # :yields: Element
       @elements.each( xpath, &block )
     end
 
-    # Synonym for Element.to_a
-    # This is a little slower than calling elements.each directly.
-    # xpath:: any XPath by which to search for elements in the tree
-    # Returns:: an array of Elements that match the supplied path
+    # :call-seq:
+    #   get_elements(xpath)
+    #
+    # Returns an array of the elements that match the given +xpath+:
+    #
+    #   xml_string = <<-EOT
+    #   <root>
+    #     <a level='1'>
+    #       <a level='2'/>
+    #     </a>
+    #   </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   d.root.get_elements('//a') # => [<a level='1'> ... </>, <a level='2'/>]
+    #
     def get_elements( xpath )
       @elements.to_a( xpath )
     end
 
-    # Returns the next sibling that is an element, or nil if there is
-    # no Element sibling after this one
-    #  doc = Document.new '<a><b/>text<c/></a>'
-    #  doc.root.elements['b'].next_element          #-> <c/>
-    #  doc.root.elements['c'].next_element          #-> nil
+    # :call-seq:
+    #   next_element
+    #
+    # Returns the next sibling that is an element if it exists,
+    # +niL+ otherwise:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   d.root.elements['b'].next_element #-> <c/>
+    #   d.root.elements['c'].next_element #-> nil
+    #
     def next_element
       element = next_sibling
       element = element.next_sibling until element.nil? or element.kind_of? Element
       return element
     end
 
-    # Returns the previous sibling that is an element, or nil if there is
-    # no Element sibling prior to this one
-    #  doc = Document.new '<a><b/>text<c/></a>'
-    #  doc.root.elements['c'].previous_element          #-> <b/>
-    #  doc.root.elements['b'].previous_element          #-> nil
+    # :call-seq:
+    #   previous_element
+    #
+    # Returns the previous sibling that is an element if it exists,
+    # +niL+ otherwise:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   d.root.elements['c'].previous_element #-> <b/>
+    #   d.root.elements['b'].previous_element #-> nil
+    #
     def previous_element
       element = previous_sibling
       element = element.previous_sibling until element.nil? or element.kind_of? Element
@@ -429,36 +987,69 @@ module REXML
     # Text                                          #
     #################################################
 
-    # Evaluates to +true+ if this element has at least one Text child
+    # :call-seq:
+    #   has_text? -> true or false
+    #
+    # Returns +true+ if the element has one or more text noded,
+    # +false+ otherwise:
+    #
+    #   d = REXML::Document.new '<a><b/>text<c/></a>'
+    #   a = d.root
+    #   a.has_text? # => true
+    #   b = a[0]
+    #   b.has_text? # => false
+    #
     def has_text?
       not text().nil?
     end
 
-    # A convenience method which returns the String value of the _first_
-    # child text element, if one exists, and +nil+ otherwise.
+    # :call-seq:
+    #   text(xpath = nil) -> text_string or nil
     #
-    # <em>Note that an element may have multiple Text elements, perhaps
-    # separated by other children</em>.  Be aware that this method only returns
-    # the first Text node.
+    # Returns the text string from the first text node child
+    # in a specified element, if it exists, +nil+ otherwise.
     #
-    # This method returns the +value+ of the first text child node, which
-    # ignores the +raw+ setting, so always returns normalized text. See
-    # the Text::value documentation.
+    # With no argument, returns the text from the first text node in +self+:
+    #
+    #   d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>"
+    #   d.root.text.class # => String
+    #   d.root.text       # => "some text "
+    #
+    # With argument +xpath+, returns text from the first text node
+    # in the element that matches +xpath+:
+    #
+    #   d.root.text(1) # => "this is bold!"
+    #
+    # Note that an element may have multiple text nodes,
+    # possibly separated by other non-text children, as above.
+    # Even so, the returned value is the string text from the first such node.
+    #
+    # Note also that the text note is retrieved by method get_text,
+    # and so is always normalized text.
     #
-    #  doc = Document.new "<p>some text <b>this is bold!</b> more text</p>"
-    #  # The element 'p' has two text elements, "some text " and " more text".
-    #  doc.root.text              #-> "some text "
     def text( path = nil )
       rv = get_text(path)
       return rv.value unless rv.nil?
       nil
     end
 
-    # Returns the first child Text node, if any, or +nil+ otherwise.
-    # This method returns the actual +Text+ node, rather than the String content.
-    #  doc = Document.new "<p>some text <b>this is bold!</b> more text</p>"
-    #  # The element 'p' has two text elements, "some text " and " more text".
-    #  doc.root.get_text.value            #-> "some text "
+    # :call-seq:
+    #   get_text(xpath = nil) -> text_node or nil
+    #
+    # Returns the first text node child in a specified element, if it exists,
+    # +nil+ otherwise.
+    #
+    # With no argument, returns the first text node from +self+:
+    #
+    #   d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>"
+    #   d.root.get_text.class # => REXML::Text
+    #   d.root.get_text       # => "some text "
+    #
+    # With argument +xpath+, returns the first text node from the element
+    # that matches +xpath+:
+    #
+    #   d.root.get_text(1) # => "this is bold!"
+    #
     def get_text path = nil
       rv = nil
       if path
@@ -470,26 +1061,31 @@ module REXML
       return rv
     end
 
-    # Sets the first Text child of this object.  See text() for a
-    # discussion about Text children.
-    #
-    # If a Text child already exists, the child is replaced by this
-    # content.  This means that Text content can be deleted by calling
-    # this method with a nil argument.  In this case, the next Text
-    # child becomes the first Text child.  In no case is the order of
-    # any siblings disturbed.
-    # text::
-    #   If a String, a new Text child is created and added to
-    #   this Element as the first Text child.  If Text, the text is set
-    #   as the first Child element.  If nil, then any existing first Text
-    #   child is removed.
-    # Returns:: this Element.
-    #  doc = Document.new '<a><b/></a>'
-    #  doc.root.text = 'Sean'      #-> '<a><b/>Sean</a>'
-    #  doc.root.text = 'Elliott'   #-> '<a><b/>Elliott</a>'
-    #  doc.root.add_element 'c'    #-> '<a><b/>Elliott<c/></a>'
-    #  doc.root.text = 'Russell'   #-> '<a><b/>Russell<c/></a>'
-    #  doc.root.text = nil         #-> '<a><b/><c/></a>'
+    # :call-seq:
+    #   text = string -> string
+    #   text = nil -> nil
+    #
+    # Adds, replaces, or removes the first text node child in the element.
+    #
+    # With string argument +string+,
+    # creates a new \REXML::Text node containing that string,
+    # honoring the current settings for whitespace and row,
+    # then places the node as the first text child in the element;
+    # returns +string+.
+    #
+    # If the element has no text child, the text node is added:
+    #
+    #   d = REXML::Document.new '<a><b/></a>'
+    #   d.root.text = 'foo' #-> '<a><b/>foo</a>'
+    #
+    # If the element has a text child, it is replaced:
+    #
+    #   d.root.text = 'bar' #-> '<a><b/>bar</a>'
+    #
+    # With argument +nil+, removes the first text child:
+    #
+    #   d.root.text = nil   #-> '<a><b/><c/></a>'
+    #
     def text=( text )
       if text.kind_of? String
         text = Text.new( text, whitespace(), nil, raw() )
@@ -509,17 +1105,45 @@ module REXML
       return self
     end
 
-    # A helper method to add a Text child.  Actual Text instances can
-    # be added with regular Parent methods, such as add() and <<()
-    # text::
-    #   if a String, a new Text instance is created and added
-    #   to the parent.  If Text, the object is added directly.
-    # Returns:: this Element
-    #  e = Element.new('a')          #-> <e/>
-    #  e.add_text 'foo'              #-> <e>foo</e>
-    #  e.add_text Text.new(' bar')    #-> <e>foo bar</e>
-    # Note that at the end of this example, the branch has <b>3</b> nodes; the 'e'
-    # element and <b>2</b> Text node children.
+    # :call-seq:
+    #   add_text(string) -> nil
+    #   add_text(text_node) -> self
+    #
+    # Adds text to the element.
+    #
+    # When string argument +string+ is given, returns +nil+.
+    #
+    # If the element has no child text node,
+    # creates a \REXML::Text object using the string,
+    # honoring the current settings for whitespace and raw,
+    # then adds that node to the element:
+    #
+    #   d = REXML::Document.new('<a><b/></a>')
+    #   a = d.root
+    #   a.add_text('foo')
+    #   a.to_a # => [<b/>, "foo"]
+    #
+    # If the element has child text nodes,
+    # appends the string to the _last_ text node:
+    #
+    #   d = REXML::Document.new('<a>foo<b/>bar</a>')
+    #   a = d.root
+    #   a.add_text('baz')
+    #   a.to_a # => ["foo", <b/>, "barbaz"]
+    #   a.add_text('baz')
+    #   a.to_a # => ["foo", <b/>, "barbazbaz"]
+    #
+    # When text node argument +text_node+ is given,
+    # appends the node as the last text node in the element;
+    # returns +self+:
+    #
+    #   d = REXML::Document.new('<a>foo<b/>bar</a>')
+    #   a = d.root
+    #   a.add_text(REXML::Text.new('baz'))
+    #   a.to_a # => ["foo", <b/>, "bar", "baz"]
+    #   a.add_text(REXML::Text.new('baz'))
+    #   a.to_a # => ["foo", <b/>, "bar", "baz", "baz"]
+    #
     def add_text( text )
       if text.kind_of? String
         if @children[-1].kind_of? Text
@@ -532,10 +1156,39 @@ module REXML
       return self
     end
 
+    # :call-seq:
+    #   node_type -> :element
+    #
+    # Returns symbol <tt>:element</tt>:
+    #
+    #   d = REXML::Document.new('<a/>')
+    #   a = d.root  # => <a/>
+    #   a.node_type # => :element
+    #
     def node_type
       :element
     end
 
+    # :call-seq:
+    #   xpath -> string_xpath
+    #
+    # Returns the string xpath to the element
+    # relative to the most distant parent:
+    #
+    #   d = REXML::Document.new('<a><b><c/></b></a>')
+    #   a = d.root # => <a> ... </>
+    #   b = a[0]   # => <b> ... </>
+    #   c = b[0]   # => <c/>
+    #   d.xpath    # => ""
+    #   a.xpath    # => "/a"
+    #   b.xpath    # => "/a/b"
+    #   c.xpath    # => "/a/b/c"
+    #
+    # If there is no parent, returns the expanded name of the element:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.xpath    # => "foo"
+    #
     def xpath
       path_elements = []
       cur = self
@@ -551,19 +1204,45 @@ module REXML
     # Attributes                                    #
     #################################################
 
-    # Fetches an attribute value or a child.
+    # :call-seq:
+    #   [index] -> object
+    #   [attr_name] -> attr_value
+    #   [attr_sym] -> attr_value
+    #
+    # With integer argument +index+ given,
+    # returns the child at offset +index+, or +nil+ if none:
+    #
+    #   d = REXML::Document.new '><root><a/>text<b/>more<c/></root>'
+    #   root = d.root
+    #   (0..root.size).each do |index|
+    #     node = root[index]
+    #     p "#{index}: #{node} (#{node.class})"
+    #   end
+    #
+    # Output:
+    #
+    #   "0: <a/> (REXML::Element)"
+    #   "1: text (REXML::Text)"
+    #   "2: <b/> (REXML::Element)"
+    #   "3: more (REXML::Text)"
+    #   "4: <c/> (REXML::Element)"
+    #   "5:  (NilClass)"
+    #
+    # With string argument +attr_name+ given,
+    # returns the string value for the given attribute name if it exists,
+    # otherwise +nil+:
     #
-    # If String or Symbol is specified, it's treated as attribute
-    # name. Attribute value as String or +nil+ is returned. This case
-    # is shortcut of +attributes[name]+.
+    #   d = REXML::Document.new('<root attr="value"></root>')
+    #   root = d.root
+    #   root['attr']   # => "value"
+    #   root['nosuch'] # => nil
     #
-    # If Integer is specified, it's treated as the index of
-    # child. It returns Nth child.
+    # With symbol argument +attr_sym+ given,
+    # returns <tt>[attr_sym.to_s]</tt>:
+    #
+    #   root[:attr]   # => "value"
+    #   root[:nosuch] # => nil
     #
-    #   doc = REXML::Document.new("<a attr='1'><b/><c/></a>")
-    #   doc.root["attr"]             # => "1"
-    #   doc.root.attributes["attr"]  # => "1"
-    #   doc.root[1]                  # => <c/>
     def [](name_or_index)
       case name_or_index
       when String
@@ -575,17 +1254,42 @@ module REXML
       end
     end
 
+
+    # :call-seq:
+    #   attribute(name, namespace = nil)
+    #
+    # Returns the string value for the given attribute name.
+    #
+    # With only argument +name+ given,
+    # returns the value of the named attribute if it exists, otherwise +nil+:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns="ns0">
+    #       <a xmlns="ns1" attr="value"></a>
+    #       <b xmlns="ns2" attr="value"></b>
+    #       <c attr="value"/>
+    #    </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   root = d.root
+    #   a = root[1] # => <a xmlns='ns1' attr='value'/>
+    #   a.attribute('attr') # => attr='value'
+    #   a.attribute('nope') # => nil
+    #
+    # With arguments +name+ and +namespace+ given,
+    # returns the value of the named attribute if it exists, otherwise +nil+:
+    #
+    #   xml_string = "<root xmlns:a='a' a:x='a:x' x='x'/>"
+    #   document = REXML::Document.new(xml_string)
+    #   document.root.attribute("x")      # => x='x'
+    #   document.root.attribute("x", "a") # => a:x='a:x'
+    #
     def attribute( name, namespace=nil )
-      prefix = nil
-      if namespaces.respond_to? :key
-        prefix = namespaces.key(namespace) if namespace
-      else
-        prefix = namespaces.index(namespace) if namespace
-      end
+      prefix = namespaces.key(namespace) if namespace
       prefix = nil if prefix == 'xmlns'
 
       ret_val =
-        attributes.get_attribute( "#{prefix ? prefix + ':' : ''}#{name}" )
+        attributes.get_attribute( prefix ? "#{prefix}:#{name}" : name )
 
       return ret_val unless ret_val.nil?
       return nil if prefix.nil?
@@ -598,29 +1302,46 @@ module REXML
 
     end
 
-    # Evaluates to +true+ if this element has any attributes set, false
-    # otherwise.
+    # :call-seq:
+    #   has_attributes? -> true or false
+    #
+    # Returns +true+ if the element has attributes, +false+ otherwise:
+    #
+    #   d = REXML::Document.new('<root><a attr="val"/><b/></root>')
+    #   a, b = *d.root
+    #   a.has_attributes? # => true
+    #   b.has_attributes? # => false
+    #
     def has_attributes?
       return !@attributes.empty?
     end
 
+    # :call-seq:
+    #   add_attribute(name, value) -> value
+    #   add_attribute(attribute) -> attribute
+    #
     # Adds an attribute to this element, overwriting any existing attribute
     # by the same name.
-    # key::
-    #   can be either an Attribute or a String.  If an Attribute,
-    #   the attribute is added to the list of Element attributes.  If String,
-    #   the argument is used as the name of the new attribute, and the value
-    #   parameter must be supplied.
-    # value::
-    #   Required if +key+ is a String, and ignored if the first argument is
-    #   an Attribute.  This is a String, and is used as the value
-    #   of the new Attribute.  This should be the unnormalized value of the
-    #   attribute (without entities).
-    # Returns:: the Attribute added
-    #  e = Element.new 'e'
-    #  e.add_attribute( 'a', 'b' )               #-> <e a='b'/>
-    #  e.add_attribute( 'x:a', 'c' )             #-> <e a='b' x:a='c'/>
-    #  e.add_attribute Attribute.new('b', 'd')   #-> <e a='b' x:a='c' b='d'/>
+    #
+    # With string argument +name+ and object +value+ are given,
+    # adds the attribute created with that name and value:
+    #
+    #   e = REXML::Element.new
+    #   e.add_attribute('attr', 'value') # => "value"
+    #   e['attr'] # => "value"
+    #   e.add_attribute('attr', 'VALUE') # => "VALUE"
+    #   e['attr'] # => "VALUE"
+    #
+    # With only attribute object +attribute+ given,
+    # adds the given attribute:
+    #
+    #   a = REXML::Attribute.new('attr', 'value')
+    #   e.add_attribute(a) # => attr='value'
+    #   e['attr'] # => "value"
+    #   a = REXML::Attribute.new('attr', 'VALUE')
+    #   e.add_attribute(a) # => attr='VALUE'
+    #   e['attr'] # => "VALUE"
+    #
     def add_attribute( key, value=nil )
       if key.kind_of? Attribute
         @attributes << key
@@ -629,10 +1350,29 @@ module REXML
       end
     end
 
-    # Add multiple attributes to this element.
-    # hash:: is either a hash, or array of arrays
-    #  el.add_attributes( {"name1"=>"value1", "name2"=>"value2"} )
-    #  el.add_attributes( [ ["name1","value1"], ["name2"=>"value2"] ] )
+    # :call-seq:
+    #   add_attributes(hash) -> hash
+    #   add_attributes(array)
+    #
+    # Adds zero or more attributes to the element;
+    # returns the argument.
+    #
+    # If hash argument +hash+ is given,
+    # each key must be a string;
+    # adds each attribute created with the key/value pair:
+    #
+    #   e = REXML::Element.new
+    #   h = {'foo' => 'bar', 'baz' => 'bat'}
+    #   e.add_attributes(h)
+    #
+    # If argument +array+ is given,
+    # each array member must be a 2-element array <tt>[name, value];
+    # each name must be a string:
+    #
+    #   e = REXML::Element.new
+    #   a = [['foo' => 'bar'], ['baz' => 'bat']]
+    #   e.add_attributes(a)
+    #
     def add_attributes hash
       if hash.kind_of? Hash
         hash.each_pair {|key, value| @attributes[key] = value }
@@ -641,19 +1381,17 @@ module REXML
       end
     end
 
-    # Removes an attribute
-    # key::
-    #   either an Attribute or a String.  In either case, the
-    #   attribute is found by matching the attribute name to the argument,
-    #   and then removed.  If no attribute is found, no action is taken.
-    # Returns::
-    #   the attribute removed, or nil if this Element did not contain
-    #   a matching attribute
-    #  e = Element.new('E')
-    #  e.add_attribute( 'name', 'Sean' )             #-> <E name='Sean'/>
-    #  r = e.add_attribute( 'sur:name', 'Russell' )  #-> <E name='Sean' sur:name='Russell'/>
-    #  e.delete_attribute( 'name' )                  #-> <E sur:name='Russell'/>
-    #  e.delete_attribute( r )                       #-> <E/>
+    # :call-seq:
+    #   delete_attribute(name) -> removed_attribute or nil
+    #
+    # Removes a named attribute if it exists;
+    # returns the removed attribute if found, otherwise +nil+:
+    #
+    #   e = REXML::Element.new('foo')
+    #   e.add_attribute('bar', 'baz')
+    #   e.delete_attribute('bar') # => <bar/>
+    #   e.delete_attribute('bar') # => nil
+    #
     def delete_attribute(key)
       attr = @attributes.get_attribute(key)
       attr.remove unless attr.nil?
@@ -663,26 +1401,80 @@ module REXML
     # Other Utilities                               #
     #################################################
 
-    # Get an array of all CData children.
-    # IMMUTABLE
+    # :call-seq:
+    #   cdatas -> array_of_cdata_children
+    #
+    # Returns a frozen array of the REXML::CData children of the element:
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #       <![CDATA[foo]]>
+    #       <![CDATA[bar]]>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   cds = d.root.cdatas      # => ["foo", "bar"]
+    #   cds.frozen?              # => true
+    #   cds.map {|cd| cd.class } # => [REXML::CData, REXML::CData]
+    #
     def cdatas
       find_all { |child| child.kind_of? CData }.freeze
     end
 
-    # Get an array of all Comment children.
-    # IMMUTABLE
+    # :call-seq:
+    #   comments -> array_of_comment_children
+    #
+    # Returns a frozen array of the REXML::Comment children of the element:
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #       <!--foo-->
+    #       <!--bar-->
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   cs = d.root.comments
+    #   cs.frozen?            # => true
+    #   cs.map {|c| c.class } # => [REXML::Comment, REXML::Comment]
+    #   cs.map {|c| c.to_s }  # => ["foo", "bar"]
+    #
     def comments
       find_all { |child| child.kind_of? Comment }.freeze
     end
 
-    # Get an array of all Instruction children.
-    # IMMUTABLE
+    # :call-seq:
+    #   instructions -> array_of_instruction_children
+    #
+    # Returns a frozen array of the REXML::Instruction children of the element:
+    #
+    #   xml_string = <<-EOT
+    #     <root>
+    #       <?target0 foo?>
+    #       <?target1 bar?>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   is = d.root.instructions
+    #   is.frozen?             # => true
+    #   is.map {|i| i.class } # => [REXML::Instruction, REXML::Instruction]
+    #   is.map {|i| i.to_s }  # => ["<?target0 foo?>", "<?target1 bar?>"]
+    #
     def instructions
       find_all { |child| child.kind_of? Instruction }.freeze
     end
 
-    # Get an array of all Text children.
-    # IMMUTABLE
+    # :call-seq:
+    #   texts -> array_of_text_children
+    #
+    # Returns a frozen array of the REXML::Text children of the element:
+    #
+    #   xml_string = '<root><a/>text<b/>more<c/></root>'
+    #   d = REXML::Document.new(xml_string)
+    #   ts = d.root.texts
+    #   ts.frozen?            # => true
+    #   ts.map {|t| t.class } # => [REXML::Text, REXML::Text]
+    #   ts.map {|t| t.to_s }  # => ["text", "more"]
+    #
     def texts
       find_all { |child| child.kind_of? Text }.freeze
     end
@@ -758,35 +1550,129 @@ module REXML
   # XPath search support.  You are expected to only encounter this class as
   # the <tt>element.elements</tt> object.  Therefore, you are
   # _not_ expected to instantiate this yourself.
+  #
+  #   xml_string = <<-EOT
+  #   <?xml version="1.0" encoding="UTF-8"?>
+  #   <bookstore>
+  #     <book category="cooking">
+  #       <title lang="en">Everyday Italian</title>
+  #       <author>Giada De Laurentiis</author>
+  #       <year>2005</year>
+  #       <price>30.00</price>
+  #     </book>
+  #     <book category="children">
+  #       <title lang="en">Harry Potter</title>
+  #       <author>J K. Rowling</author>
+  #       <year>2005</year>
+  #       <price>29.99</price>
+  #     </book>
+  #     <book category="web">
+  #       <title lang="en">XQuery Kick Start</title>
+  #       <author>James McGovern</author>
+  #       <author>Per Bothner</author>
+  #       <author>Kurt Cagle</author>
+  #       <author>James Linn</author>
+  #       <author>Vaidyanathan Nagarajan</author>
+  #       <year>2003</year>
+  #       <price>49.99</price>
+  #     </book>
+  #     <book category="web" cover="paperback">
+  #       <title lang="en">Learning XML</title>
+  #       <author>Erik T. Ray</author>
+  #       <year>2003</year>
+  #       <price>39.95</price>
+  #     </book>
+  #   </bookstore>
+  #   EOT
+  #   d = REXML::Document.new(xml_string)
+  #   elements = d.root.elements
+  #   elements # => #<REXML::Elements @element=<bookstore> ... </>>
+  #
   class Elements
     include Enumerable
-    # Constructor
-    # parent:: the parent Element
+    # :call-seq:
+    #   new(parent) -> new_elements_object
+    #
+    # Returns a new \Elements object with the given +parent+.
+    # Does _not_ assign <tt>parent.elements = self</tt>:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   eles = REXML::Elements.new(d.root)
+    #   eles # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles == d.root.elements # => false
+    #
     def initialize parent
       @element = parent
     end
 
-    # Fetches a child element.  Filters only Element children, regardless of
-    # the XPath match.
-    # index::
-    #   the search parameter.  This is either an Integer, which
-    #   will be used to find the index'th child Element, or an XPath,
-    #   which will be used to search for the Element.  <em>Because
-    #   of the nature of XPath searches, any element in the connected XML
-    #   document can be fetched through any other element.</em>  <b>The
-    #   Integer index is 1-based, not 0-based.</b>  This means that the first
-    #   child element is at index 1, not 0, and the +n+th element is at index
-    #   +n+, not <tt>n-1</tt>.  This is because XPath indexes element children
-    #   starting from 1, not 0, and the indexes should be the same.
-    # name::
-    #   optional, and only used in the first argument is an
-    #   Integer.  In that case, the index'th child Element that has the
-    #   supplied name will be returned.  Note again that the indexes start at 1.
-    # Returns:: the first matching Element, or nil if no child matched
-    #  doc = Document.new '<a><b/><c id="1"/><c id="2"/><d/></a>'
-    #  doc.root.elements[1]       #-> <b/>
-    #  doc.root.elements['c']     #-> <c id="1"/>
-    #  doc.root.elements[2,'c']   #-> <c id="2"/>
+    # :call-seq:
+    #   parent
+    #
+    # Returns the parent element cited in creating the \Elements object.
+    # This element is also the default starting point for searching
+    # in the \Elements object.
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = REXML::Elements.new(d.root)
+    #   elements.parent == d.root # => true
+    #
+    def parent
+      @element
+    end
+
+    # :call-seq:
+    #   elements[index] -> element or nil
+    #   elements[xpath] -> element or nil
+    #   elements[n, name] -> element or nil
+    #
+    # Returns the first \Element object selected by the arguments,
+    # if any found, or +nil+ if none found.
+    #
+    # Notes:
+    # - The +index+ is 1-based, not 0-based, so that:
+    #   - The first element has index <tt>1</tt>
+    #   - The _nth_ element has index +n+.
+    # - The selection ignores non-\Element nodes.
+    #
+    # When the single argument +index+ is given,
+    # returns the element given by the index, if any; otherwise, +nil+:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   eles = d.root.elements
+    #   eles # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles[1] # => <book category='cooking'> ... </>
+    #   eles.size # => 4
+    #   eles[4] # => <book category='web' cover='paperback'> ... </>
+    #   eles[5] # => nil
+    #
+    # The node at this index is not an \Element, and so is not returned:
+    #
+    #   eles = d.root.first.first # => <title lang='en'> ... </>
+    #   eles.to_a # => ["Everyday Italian"]
+    #   eles[1] # => nil
+    #
+    # When the single argument +xpath+ is given,
+    # returns the first element found via that +xpath+, if any; otherwise, +nil+:
+    #
+    #   eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles['/bookstore']                    # => <bookstore> ... </>
+    #   eles['//book']                        # => <book category='cooking'> ... </>
+    #   eles['//book [@category="children"]'] # => <book category='children'> ... </>
+    #   eles['/nosuch']                       # => nil
+    #   eles['//nosuch']                      # => nil
+    #   eles['//book [@category="nosuch"]']   # => nil
+    #   eles['.']                             # => <bookstore> ... </>
+    #   eles['..'].class                      # => REXML::Document
+    #
+    # With arguments +n+ and +name+ given,
+    # returns the _nth_ found element that has the given +name+,
+    # or +nil+ if there is no such _nth_ element:
+    #
+    #   eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles[1, 'book'] # => <book category='cooking'> ... </>
+    #   eles[4, 'book'] # => <book category='web' cover='paperback'> ... </>
+    #   eles[5, 'book'] # => nil
+    #
     def []( index, name=nil)
       if index.kind_of? Integer
         raise "index (#{index}) must be >= 1" if index < 1
@@ -806,19 +1692,42 @@ module REXML
       end
     end
 
-    # Sets an element, replacing any previous matching element.  If no
-    # existing element is found ,the element is added.
-    # index:: Used to find a matching element to replace.  See []().
-    # element::
-    #   The element to replace the existing element with
-    #   the previous element
-    # Returns:: nil if no previous element was found.
+    # :call-seq:
+    #  elements[] = index, replacement_element -> replacement_element or nil
+    #
+    # Replaces or adds an element.
+    #
+    # When <tt>eles[index]</tt> exists, replaces it with +replacement_element+
+    # and returns +replacement_element+:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles[1] # => <book category='cooking'> ... </>
+    #   eles[1] = REXML::Element.new('foo')
+    #   eles[1] # => <foo/>
+    #
+    # Does nothing (or raises an exception)
+    # if +replacement_element+ is not an \Element:
+    #   eles[2] # => <book category='web' cover='paperback'> ... </>
+    #   eles[2] = REXML::Text.new('bar')
+    #   eles[2] # => <book category='web' cover='paperback'> ... </>
+    #
+    # When <tt>eles[index]</tt> does not exist,
+    # adds +replacement_element+ to the element and returns
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>>
+    #   eles.size # => 4
+    #   eles[50] = REXML::Element.new('foo') # => <foo/>
+    #   eles.size # => 5
+    #   eles[5] # => <foo/>
+    #
+    # Does nothing (or raises an exception)
+    # if +replacement_element+ is not an \Element:
+    #
+    #   eles[50] = REXML::Text.new('bar') # => "bar"
+    #   eles.size # => 5
     #
-    #  doc = Document.new '<a/>'
-    #  doc.root.elements[10] = Element.new('b')    #-> <a><b/></a>
-    #  doc.root.elements[1]                        #-> <b/>
-    #  doc.root.elements[1] = Element.new('c')     #-> <a><c/></a>
-    #  doc.root.elements['c'] = Element.new('d')   #-> <a><d/></a>
     def []=( index, element )
       previous = self[index]
       if previous.nil?
@@ -829,14 +1738,34 @@ module REXML
       return previous
     end
 
-    # Returns +true+ if there are no +Element+ children, +false+ otherwise
+    # :call-seq:
+    #   empty? -> true or false
+    #
+    # Returns +true+ if there are no children, +false+ otherwise.
+    #
+    #   d = REXML::Document.new('')
+    #   d.elements.empty? # => true
+    #   d = REXML::Document.new(xml_string)
+    #   d.elements.empty? # => false
+    #
     def empty?
       @element.find{ |child| child.kind_of? Element}.nil?
     end
 
-    # Returns the index of the supplied child (starting at 1), or -1 if
-    # the element is not a child
-    # element:: an +Element+ child
+    # :call-seq:
+    #   index(element)
+    #
+    # Returns the 1-based index of the given +element+, if found;
+    # otherwise, returns -1:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   ele_1, ele_2, ele_3, ele_4 = *elements
+    #   elements.index(ele_4) # => 4
+    #   elements.delete(ele_3)
+    #   elements.index(ele_4) # => 3
+    #   elements.index(ele_3) # => -1
+    #
     def index element
       rv = 0
       found = @element.find do |child|
@@ -848,17 +1777,47 @@ module REXML
       return -1
     end
 
-    # Deletes a child Element
-    # element::
-    #   Either an Element, which is removed directly; an
-    #   xpath, where the first matching child is removed; or an Integer,
-    #   where the n'th Element is removed.
-    # Returns:: the removed child
-    #  doc = Document.new '<a><b/><c/><c id="1"/></a>'
-    #  b = doc.root.elements[1]
-    #  doc.root.elements.delete b           #-> <a><c/><c id="1"/></a>
-    #  doc.elements.delete("a/c[@id='1']")  #-> <a><c/></a>
-    #  doc.root.elements.delete 1           #-> <a/>
+    # :call-seq:
+    #   delete(index) -> removed_element or nil
+    #   delete(element) -> removed_element or nil
+    #   delete(xpath) -> removed_element or nil
+    #
+    # Removes an element; returns the removed element, or +nil+ if none removed.
+    #
+    # With integer argument +index+ given,
+    # removes the child element at that offset:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.size # => 4
+    #   elements[2] # => <book category='children'> ... </>
+    #   elements.delete(2) # => <book category='children'> ... </>
+    #   elements.size # => 3
+    #   elements[2] # => <book category='web'> ... </>
+    #   elements.delete(50) # => nil
+    #
+    # With element argument +element+ given,
+    # removes that child element:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   ele_1, ele_2, ele_3, ele_4 = *elements
+    #   elements.size # => 4
+    #   elements[2] # => <book category='children'> ... </>
+    #   elements.delete(ele_2) # => <book category='children'> ... </>
+    #   elements.size # => 3
+    #   elements[2] # => <book category='web'> ... </>
+    #   elements.delete(ele_2) # => nil
+    #
+    # With string argument +xpath+ given,
+    # removes the first element found via that xpath:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.delete('//book') # => <book category='cooking'> ... </>
+    #   elements.delete('//book [@category="children"]') # => <book category='children'> ... </>
+    #   elements.delete('//nosuch') # => nil
+    #
     def delete element
       if element.kind_of? Element
         @element.delete element
@@ -868,12 +1827,23 @@ module REXML
       end
     end
 
-    # Removes multiple elements.  Filters for Element children, regardless of
-    # XPath matching.
-    # xpath:: all elements matching this String path are removed.
-    # Returns:: an Array of Elements that have been removed
-    #  doc = Document.new '<a><c/><c/><c/><c/></a>'
-    #  deleted = doc.elements.delete_all 'a/c' #-> [<c/>, <c/>, <c/>, <c/>]
+    # :call-seq:
+    #   delete_all(xpath)
+    #
+    # Removes all elements found via the given +xpath+;
+    # returns the array of removed elements, if any, else +nil+.
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.size # => 4
+    #   deleted_elements = elements.delete_all('//book [@category="web"]')
+    #   deleted_elements.size # => 2
+    #   elements.size # => 2
+    #   deleted_elements = elements.delete_all('//book')
+    #   deleted_elements.size # => 2
+    #   elements.size # => 0
+    #   elements.delete_all('//book') # => []
+    #
     def delete_all( xpath )
       rv = []
       XPath::each( @element, xpath) {|element|
@@ -886,15 +1856,68 @@ module REXML
       return rv
     end
 
-    # Adds an element
-    # element::
-    #   if supplied, is either an Element, String, or
-    #   Source (see Element.initialize).  If not supplied or nil, a
-    #   new, default Element will be constructed
-    # Returns:: the added Element
-    #  a = Element.new('a')
-    #  a.elements.add(Element.new('b'))  #-> <a><b/></a>
-    #  a.elements.add('c')               #-> <a><b/><c/></a>
+    # :call-seq:
+    #   add -> new_element
+    #   add(name) -> new_element
+    #   add(element) -> element
+    #
+    # Adds an element; returns the element added.
+    #
+    # With no argument, creates and adds a new element.
+    # The new element has:
+    #
+    # - No name.
+    # - \Parent from the \Elements object.
+    # - Context from the that parent.
+    #
+    # Example:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   parent = elements.parent     # => <bookstore> ... </>
+    #   parent.context = {raw: :all}
+    #   elements.size                # => 4
+    #   new_element = elements.add   # => </>
+    #   elements.size                # => 5
+    #   new_element.name             # => nil
+    #   new_element.parent           # => <bookstore> ... </>
+    #   new_element.context          # => {:raw=>:all}
+    #
+    # With string argument +name+, creates and adds a new element.
+    # The new element has:
+    #
+    # - Name +name+.
+    # - \Parent from the \Elements object.
+    # - Context from the that parent.
+    #
+    # Example:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   parent = elements.parent          # => <bookstore> ... </>
+    #   parent.context = {raw: :all}
+    #   elements.size                     # => 4
+    #   new_element = elements.add('foo') # => <foo/>
+    #   elements.size                     # => 5
+    #   new_element.name                  # => "foo"
+    #   new_element.parent                # => <bookstore> ... </>
+    #   new_element.context               # => {:raw=>:all}
+    #
+    # With argument +element+,
+    # creates and adds a clone of the given +element+.
+    # The new element has name, parent, and context from the given +element+.
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.size                 # => 4
+    #   e0 = REXML::Element.new('foo')
+    #   e1 = REXML::Element.new('bar', e0, {raw: :all})
+    #   element = elements.add(e1) # => <bar/>
+    #   elements.size                 # => 5
+    #   element.name                  # => "bar"
+    #   element.parent                # => <bookstore> ... </>
+    #   element.context               # => {:raw=>:all}
+    #
     def add element=nil
       if element.nil?
         Element.new("", self, @element.context)
@@ -909,24 +1932,55 @@ module REXML
 
     alias :<< :add
 
-    # Iterates through all of the child Elements, optionally filtering
-    # them by a given XPath
-    # xpath::
-    #   optional.  If supplied, this is a String XPath, and is used to
-    #   filter the children, so that only matching children are yielded.  Note
-    #   that XPaths are automatically filtered for Elements, so that
-    #   non-Element children will not be yielded
-    #  doc = Document.new '<a><b/><c/><d/>sean<b/><c/><d/></a>'
-    #  doc.root.elements.each {|e|p e}       #-> Yields b, c, d, b, c, d elements
-    #  doc.root.elements.each('b') {|e|p e}  #-> Yields b, b elements
-    #  doc.root.elements.each('child::node()')  {|e|p e}
-    #  #-> Yields <b/>, <c/>, <d/>, <b/>, <c/>, <d/>
-    #  XPath.each(doc.root, 'child::node()', &block)
-    #  #-> Yields <b/>, <c/>, <d/>, sean, <b/>, <c/>, <d/>
+    # :call-seq:
+    #    each(xpath = nil) {|element| ... } -> self
+    #
+    # Iterates over the elements.
+    #
+    # With no argument, calls the block with each element:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.each {|element| p element }
+    #
+    # Output:
+    #
+    #   <book category='cooking'> ... </>
+    #   <book category='children'> ... </>
+    #   <book category='web'> ... </>
+    #   <book category='web' cover='paperback'> ... </>
+    #
+    # With argument +xpath+, calls the block with each element
+    # that matches the given +xpath+:
+    #
+    #   elements.each('//book [@category="web"]') {|element| p element }
+    #
+    # Output:
+    #
+    #   <book category='web'> ... </>
+    #   <book category='web' cover='paperback'> ... </>
+    #
     def each( xpath=nil )
       XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element }
     end
 
+    # :call-seq:
+    #   collect(xpath = nil) {|element| ... } -> array
+    #
+    # Iterates over the elements; returns the array of block return values.
+    #
+    # With no argument, iterates over all elements:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.collect {|element| element.size } # => [9, 9, 17, 9]
+    #
+    # With argument +xpath+, iterates over elements that match
+    # the given +xpath+:
+    #
+    #   xpath = '//book [@category="web"]'
+    #   elements.collect(xpath) {|element| element.size } # => [17, 9]
+    #
     def collect( xpath=nil )
       collection = []
       XPath::each( @element, xpath ) {|e|
@@ -935,6 +1989,83 @@ module REXML
       collection
     end
 
+    # :call-seq:
+    #   inject(xpath = nil, initial = nil) -> object
+    #
+    # Calls the block with elements; returns the last block return value.
+    #
+    # With no argument, iterates over the elements, calling the block
+    # <tt>elements.size - 1</tt> times.
+    #
+    # - The first call passes the first and second elements.
+    # - The second call passes the first block return value and the third element.
+    # - The third call passes the second block return value and the fourth element.
+    # - And so on.
+    #
+    # In this example, the block returns the passed element,
+    # which is then the object argument to the next call:
+    #
+    #   d = REXML::Document.new(xml_string)
+    #   elements = d.root.elements
+    #   elements.inject do |object, element|
+    #     p [elements.index(object), elements.index(element)]
+    #     element
+    #   end
+    #
+    # Output:
+    #
+    #   [1, 2]
+    #   [2, 3]
+    #   [3, 4]
+    #
+    # With the single argument +xpath+, calls the block only with
+    # elements matching that xpath:
+    #
+    #   elements.inject('//book [@category="web"]') do |object, element|
+    #     p [elements.index(object), elements.index(element)]
+    #     element
+    #   end
+    #
+    # Output:
+    #
+    #  [3, 4]
+    #
+    # With argument +xpath+ given as +nil+
+    # and argument +initial+ also given,
+    # calls the block once for each element.
+    #
+    # - The first call passes the +initial+ and the first element.
+    # - The second call passes the first block return value and the second element.
+    # - The third call passes the second block return value and the third element.
+    # - And so on.
+    #
+    # In this example, the first object index is <tt>-1</tt>
+    #
+    #   elements.inject(nil, 'Initial') do |object, element|
+    #     p [elements.index(object), elements.index(element)]
+    #     element
+    #   end
+    #
+    # Output:
+    #
+    #   [-1, 1]
+    #   [1, 2]
+    #   [2, 3]
+    #   [3, 4]
+    #
+    # In this form the passed object can be used as an accumulator:
+    #
+    #   elements.inject(nil, 0) do |total, element|
+    #     total += element.size
+    #   end # => 44
+    #
+    # With both arguments +xpath+ and +initial+ are given,
+    # calls the block only with elements matching that xpath:
+    #
+    #   elements.inject('//book [@category="web"]', 0) do |total, element|
+    #     total += element.size
+    #   end # => 26
+    #
     def inject( xpath=nil, initial=nil )
       first = true
       XPath::each( @element, xpath ) {|e|
@@ -950,23 +2081,39 @@ module REXML
       initial
     end
 
-    # Returns the number of +Element+ children of the parent object.
-    #  doc = Document.new '<a>sean<b/>elliott<b/>russell<b/></a>'
-    #  doc.root.size            #-> 6, 3 element and 3 text nodes
-    #  doc.root.elements.size   #-> 3
+    # :call-seq:
+    #   size -> integer
+    #
+    # Returns the count of \Element children:
+    #
+    #   d = REXML::Document.new '<a>sean<b/>elliott<b/>russell<b/></a>'
+    #   d.root.elements.size # => 3 # Three elements.
+    #   d.root.size          # => 6 # Three elements plus three text nodes..
+    #
     def size
       count = 0
       @element.each {|child| count+=1 if child.kind_of? Element }
       count
     end
 
-    # Returns an Array of Element children.  An XPath may be supplied to
-    # filter the children.  Only Element children are returned, even if the
-    # supplied XPath matches non-Element children.
-    #  doc = Document.new '<a>sean<b/>elliott<c/></a>'
-    #  doc.root.elements.to_a                  #-> [ <b/>, <c/> ]
-    #  doc.root.elements.to_a("child::node()") #-> [ <b/>, <c/> ]
-    #  XPath.match(doc.root, "child::node()")  #-> [ sean, <b/>, elliott, <c/> ]
+    # :call-seq:
+    #   to_a(xpath = nil) -> array_of_elements
+    #
+    # Returns an array of element children (not including non-element children).
+    #
+    # With no argument, returns an array of all element children:
+    #
+    #   d = REXML::Document.new '<a>sean<b/>elliott<c/></a>'
+    #   elements = d.root.elements
+    #   elements.to_a # => [<b/>, <c/>]               # Omits non-element children.
+    #   children = d.root.children
+    #   children # => ["sean", <b/>, "elliott", <c/>] # Includes non-element children.
+    #
+    # With argument +xpath+, returns an array of element children
+    # that match the xpath:
+    #
+    #   elements.to_a('//c') # => [<c/>]
+    #
     def to_a( xpath=nil )
       rv = XPath.match( @element, xpath )
       return rv.find_all{|e| e.kind_of? Element} if xpath
@@ -988,36 +2135,89 @@ module REXML
   # A class that defines the set of Attributes of an Element and provides
   # operations for accessing elements in that set.
   class Attributes < Hash
-    # Constructor
-    # element:: the Element of which this is an Attribute
+
+    # :call-seq:
+    #   new(element)
+    #
+    # Creates and returns a new \REXML::Attributes object.
+    # The element given by argument +element+ is stored,
+    # but its own attributes are not modified:
+    #
+    #   ele = REXML::Element.new('foo')
+    #   attrs = REXML::Attributes.new(ele)
+    #   attrs.object_id == ele.attributes.object_id # => false
+    #
+    # Other instance methods in class \REXML::Attributes may refer to:
+    #
+    # - +element.document+.
+    # - +element.prefix+.
+    # - +element.expanded_name+.
+    #
     def initialize element
       @element = element
     end
 
-    # Fetches an attribute value.  If you want to get the Attribute itself,
-    # use get_attribute()
-    # name:: an XPath attribute name.  Namespaces are relevant here.
-    # Returns::
-    #   the String value of the matching attribute, or +nil+ if no
-    #   matching attribute was found.  This is the unnormalized value
-    #   (with entities expanded).
+    # :call-seq:
+    #   [name] -> attribute_value or nil
+    #
+    # Returns the value for the attribute given by +name+,
+    # if it exists; otherwise +nil+.
+    # The value returned is the unnormalized attribute value,
+    # with entities expanded:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   ele.attributes['att']     # => "<"
+    #   ele.attributes['bar:att'] # => "2"
+    #   ele.attributes['nosuch']  # => nil
+    #
+    # Related: get_attribute (returns an \Attribute object).
     #
-    #  doc = Document.new "<a foo:att='1' bar:att='2' att='&lt;'/>"
-    #  doc.root.attributes['att']         #-> '<'
-    #  doc.root.attributes['bar:att']     #-> '2'
     def [](name)
       attr = get_attribute(name)
       return attr.value unless attr.nil?
       return nil
     end
 
+    # :call-seq:
+    #   to_a -> array_of_attribute_objects
+    #
+    # Returns an array of \REXML::Attribute objects representing
+    # the attributes:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele']   # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes.to_a      # => [foo:att='1', bar:att='2', att='&lt;']
+    #   attrs.first.class                # => REXML::Attribute
+    #
     def to_a
       enum_for(:each_attribute).to_a
     end
 
-    # Returns the number of attributes the owning Element contains.
-    #  doc = Document "<a x='1' y='2' foo:x='3'/>"
-    #  doc.root.attributes.length        #-> 3
+    # :call-seq:
+    #   length
+    #
+    # Returns the count of attributes:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele']   # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   ele.attributes.length # => 3
+    #
     def length
       c = 0
       each_attribute { c+=1 }
@@ -1025,13 +2225,28 @@ module REXML
     end
     alias :size :length
 
-    # Iterates over the attributes of an Element.  Yields actual Attribute
-    # nodes, not String values.
+    # :call-seq:
+    #   each_attribute {|attr| ... }
+    #
+    # Calls the given block with each \REXML::Attribute object:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele']   # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   ele.attributes.each_attribute do |attr|
+    #     p [attr.class, attr]
+    #   end
+    #
+    # Output:
+    #
+    #   [REXML::Attribute, foo:att='1']
+    #   [REXML::Attribute, bar:att='2']
+    #   [REXML::Attribute, att='&lt;']
     #
-    #  doc = Document.new '<a x="1" y="2"/>'
-    #  doc.root.attributes.each_attribute {|attr|
-    #    p attr.expanded_name+" => "+attr.value
-    #  }
     def each_attribute # :yields: attribute
       return to_enum(__method__) unless block_given?
       each_value do |val|
@@ -1043,11 +2258,28 @@ module REXML
       end
     end
 
-    # Iterates over each attribute of an Element, yielding the expanded name
-    # and value as a pair of Strings.
+    # :call-seq:
+    #   each {|expanded_name, value| ... }
+    #
+    # Calls the given block with each expanded-name/value pair:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele']   # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   ele.attributes.each do |expanded_name, value|
+    #     p [expanded_name, value]
+    #   end
+    #
+    # Output:
+    #
+    #   ["foo:att", "1"]
+    #   ["bar:att", "2"]
+    #   ["att", "<"]
     #
-    #  doc = Document.new '<a x="1" y="2"/>'
-    #  doc.root.attributes.each {|name, value| p name+" => "+value }
     def each
       return to_enum(__method__) unless block_given?
       each_attribute do |attr|
@@ -1055,15 +2287,25 @@ module REXML
       end
     end
 
-    # Fetches an attribute
-    # name::
-    #   the name by which to search for the attribute.  Can be a
-    #   <tt>prefix:name</tt> namespace name.
-    # Returns:: The first matching attribute, or nil if there was none.  This
-    # value is an Attribute node, not the String value of the attribute.
-    #  doc = Document.new '<a x:foo="1" foo="2" bar="3"/>'
-    #  doc.root.attributes.get_attribute("foo").value    #-> "2"
-    #  doc.root.attributes.get_attribute("x:foo").value  #-> "1"
+    # :call-seq:
+    #   get_attribute(name) -> attribute_object or nil
+    #
+    # Returns the \REXML::Attribute object for the given +name+:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs.get_attribute('foo:att')       # => foo:att='1'
+    #   attrs.get_attribute('foo:att').class # => REXML::Attribute
+    #   attrs.get_attribute('bar:att')       # => bar:att='2'
+    #   attrs.get_attribute('att')           # => att='&lt;'
+    #   attrs.get_attribute('nosuch')        # => nil
+    #
     def get_attribute( name )
       attr = fetch( name, nil )
       if attr.nil?
@@ -1097,18 +2339,29 @@ module REXML
       return attr
     end
 
-    # Sets an attribute, overwriting any existing attribute value by the
-    # same name.  Namespace is significant.
-    # name:: the name of the attribute
-    # value::
-    #   (optional) If supplied, the value of the attribute.  If
-    #   nil, any existing matching attribute is deleted.
-    # Returns::
-    #   Owning element
-    #  doc = Document.new "<a x:foo='1' foo='3'/>"
-    #  doc.root.attributes['y:foo'] = '2'
-    #  doc.root.attributes['foo'] = '4'
-    #  doc.root.attributes['x:foo'] = nil
+    # :call-seq:
+    #   [name] = value -> value
+    #
+    # When +value+ is non-+nil+,
+    # assigns that to the attribute for the given +name+,
+    # overwriting the previous value if it exists:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs['foo:att'] = '2' # => "2"
+    #   attrs['baz:att'] = '3' # => "3"
+    #
+    # When +value+ is +nil+, deletes the attribute if it exists:
+    #
+    #   attrs['baz:att'] = nil
+    #   attrs.include?('baz:att') # => false
+    #
     def []=( name, value )
       if value.nil?             # Delete the named attribute
         attr = get_attribute(name)
@@ -1131,17 +2384,6 @@ module REXML
       elsif old_attr.kind_of? Hash
         old_attr[value.prefix] = value
       elsif old_attr.prefix != value.prefix
-        # Check for conflicting namespaces
-        if value.prefix != "xmlns" and old_attr.prefix != "xmlns"
-          old_namespace = old_attr.namespace
-          new_namespace = value.namespace
-          if old_namespace == new_namespace
-            raise ParseException.new(
-                    "Namespace conflict in adding attribute \"#{value.name}\": "+
-                    "Prefix \"#{old_attr.prefix}\" = \"#{old_namespace}\" and "+
-                    "prefix \"#{value.prefix}\" = \"#{new_namespace}\"")
-          end
-        end
         store value.name, {old_attr.prefix => old_attr,
                            value.prefix    => value}
       else
@@ -1150,12 +2392,17 @@ module REXML
       return @element
     end
 
-    # Returns an array of Strings containing all of the prefixes declared
-    # by this set of # attributes.  The array does not include the default
+    # :call-seq:
+    #   prefixes -> array_of_prefix_strings
+    #
+    # Returns an array of prefix strings in the attributes.
+    # The array does not include the default
     # namespace declaration, if one exists.
-    #  doc = Document.new("<a xmlns='foo' xmlns:x='bar' xmlns:y='twee' "+
-    #        "z='glorp' p:k='gru'/>")
-    #  prefixes = doc.root.attributes.prefixes    #-> ['x', 'y']
+    #
+    #   xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>'
+    #   d = REXML::Document.new(xml_string)
+    #   d.root.attributes.prefixes # => ["x", "y"]
+    #
     def prefixes
       ns = []
       each_attribute do |attribute|
@@ -1172,6 +2419,15 @@ module REXML
       ns
     end
 
+    # :call-seq:
+    #   namespaces
+    #
+    # Returns a hash of name/value pairs for the namespaces:
+    #
+    #   xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>'
+    #   d = REXML::Document.new(xml_string)
+    #   d.root.attributes.namespaces # => {"xmlns"=>"foo", "x"=>"bar", "y"=>"twee"}
+    #
     def namespaces
       namespaces = {}
       each_attribute do |attribute|
@@ -1188,16 +2444,34 @@ module REXML
       namespaces
     end
 
-    # Removes an attribute
-    # attribute::
-    #   either a String, which is the name of the attribute to remove --
-    #   namespaces are significant here -- or the attribute to remove.
-    # Returns:: the owning element
-    #  doc = Document.new "<a y:foo='0' x:foo='1' foo='3' z:foo='4'/>"
-    #  doc.root.attributes.delete 'foo'   #-> <a y:foo='0' x:foo='1' z:foo='4'/>"
-    #  doc.root.attributes.delete 'x:foo' #-> <a y:foo='0' z:foo='4'/>"
-    #  attr = doc.root.attributes.get_attribute('y:foo')
-    #  doc.root.attributes.delete attr    #-> <a z:foo='4'/>"
+    # :call-seq:
+    #    delete(name) -> element
+    #    delete(attribute) -> element
+    #
+    # Removes a specified attribute if it exists;
+    # returns the attributes' element.
+    #
+    # When string argument +name+ is given,
+    # removes the attribute of that name if it exists:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs.delete('foo:att') # => <ele bar:att='2' att='&lt;'/>
+    #   attrs.delete('foo:att') # => <ele bar:att='2' att='&lt;'/>
+    #
+    # When attribute argument +attribute+ is given,
+    # removes that attribute if it exists:
+    #
+    #   attr = REXML::Attribute.new('bar:att', '2')
+    #   attrs.delete(attr) # => <ele att='&lt;'/> # => <ele att='&lt;'/>
+    #   attrs.delete(attr) # => <ele att='&lt;'/> # => <ele/>
+    #
     def delete( attribute )
       name = nil
       prefix = nil
@@ -1225,19 +2499,48 @@ module REXML
       @element
     end
 
-    # Adds an attribute, overriding any existing attribute by the
-    # same name.  Namespaces are significant.
-    # attribute:: An Attribute
+    # :call-seq:
+    #   add(attribute) -> attribute
+    #
+    # Adds attribute +attribute+, replacing the previous
+    # attribute of the same name if it exists;
+    # returns +attribute+:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs # => {"att"=>{"foo"=>foo:att='1', "bar"=>bar:att='2', ""=>att='&lt;'}}
+    #   attrs.add(REXML::Attribute.new('foo:att', '2')) # => foo:att='2'
+    #   attrs.add(REXML::Attribute.new('baz', '3')) # => baz='3'
+    #   attrs.include?('baz') # => true
+    #
     def add( attribute )
       self[attribute.name] = attribute
     end
 
     alias :<< :add
 
-    # Deletes all attributes matching a name.  Namespaces are significant.
-    # name::
-    #   A String; all attributes that match this path will be removed
-    # Returns:: an Array of the Attributes that were removed
+    # :call-seq:
+    #   delete_all(name) -> array_of_removed_attributes
+    #
+    # Removes all attributes matching the given +name+;
+    # returns an array of the removed attributes:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs.delete_all('att') # => [att='&lt;']
+    #
     def delete_all( name )
       rv = []
       each_attribute { |attribute|
@@ -1247,11 +2550,23 @@ module REXML
       return rv
     end
 
-    # The +get_attribute_ns+ method retrieves a method by its namespace
-    # and name. Thus it is possible to reliably identify an attribute
-    # even if an XML processor has changed the prefix.
+    # :call-seq:
+    #   get_attribute_ns(namespace, name)
+    #
+    # Returns the \REXML::Attribute object among the attributes
+    # that matches the given +namespace+ and +name+:
+    #
+    #   xml_string = <<-EOT
+    #     <root xmlns:foo="http://foo" xmlns:bar="http://bar">
+    #        <ele foo:att='1' bar:att='2' att='&lt;'/>
+    #     </root>
+    #   EOT
+    #   d = REXML::Document.new(xml_string)
+    #   ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='&lt;'/>
+    #   attrs = ele.attributes
+    #   attrs.get_attribute_ns('http://foo', 'att')    # => foo:att='1'
+    #   attrs.get_attribute_ns('http://foo', 'nosuch') # => nil
     #
-    # Method contributed by Henrik Martensson
     def get_attribute_ns(namespace, name)
       result = nil
       each_attribute() { |attribute|