From d6d3ab1fefb30b03b8576864ce975401547eb4c3 Mon Sep 17 00:00:00 2001
From: tjcrowder <tj@crowdersoftware.com>
Date: Fri, 9 Oct 2009 13:36:14 +0100
Subject: [PATCH] doc: Merged/updated old docs for Element constructor

---
 src/dom/dom.js | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/dom/dom.js b/src/dom/dom.js
index b5f7765..4d44a83 100644
--- a/src/dom/dom.js
+++ b/src/dom/dom.js
@@ -90,11 +90,25 @@ if (!Node.ELEMENT_NODE) {
 
 /**
  *  new Element(tagName[, attributes])
- *    - tagName (String): The name of the HTML element to create.
- *    - attributes (Object): A list of attribute/value pairs to set on the
- *      element.
+ *  - tagName (String): The name of the HTML element to create.
+ *  - attributes (Object): An optional group of attribute/value pairs to set on
+ *    the element.
  *
- *  Creates an HTML element with `tagName` as the tag name.
+ *  Creates an HTML element with `tagName` as the tag name, optionally with the
+ *  given attributes. This can be markedly more concise than working directly
+ *  with the DOM methods, and takes advantage of Prototype's workarounds for
+ *  various browser issues with certain attributes:
+ *
+ *  ##### Example
+ *
+ *      // The old way:
+ *      var a = document.createElement('a');
+ *      a.setAttribute('class', 'foo');
+ *      a.setAttribute('href', '/foo.html');
+ *      a.appendChild(document.createTextNode("Next page"));
+ *
+ *      // The new way:
+ *      var a = new Element('a', {'class': 'foo', href: '/foo.html'}).update("Next page");
 **/
 (function(global) {