From b0159bdba7b90f504bf225887cf03aedfcc00ee4 Mon Sep 17 00:00:00 2001
From: Tobie Langel <tobie.langel@gmail.com>
Date: Fri, 23 Oct 2009 12:53:03 +0200
Subject: [PATCH] Document Prototype.Selector API.

---
 src/dom.js          |  6 ++++++
 src/dom/selector.js | 48 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/src/dom.js b/src/dom.js
index 1d9fdf3..1fb0187 100644
--- a/src/dom.js
+++ b/src/dom.js
@@ -19,6 +19,12 @@
  *
 **/
 
+/** section: DOM
+ * Prototype
+ * 
+ * The Prototype namespace.
+ *
+**/
 
 //= require "dom/dom"
 //= require <selector_engine>
diff --git a/src/dom/selector.js b/src/dom/selector.js
index 4b03a25..94d8f4c 100644
--- a/src/dom/selector.js
+++ b/src/dom/selector.js
@@ -98,4 +98,50 @@
 window.$$ = function() {
   var expression = $A(arguments).join(', ');
   return Prototype.Selector.select(expression, document);
-};
\ No newline at end of file
+};
+
+/**
+ * Prototype.Selector
+ *
+ * A namespace that acts as a wrapper around
+ * the choosen selector engine (Sizzle by default).
+ *
+**/
+
+// Implementation provided by selector engine.
+
+/**
+ *  Prototype.Selector.select(expression[, root = document]) -> [Element...]
+ *  - expression (String): A CSS selector.
+ *  - root (Element | document): A "scope" to search within. All results will
+ *    be descendants of this node.
+ *
+ *  Searches `root` for elements that match the provided CSS selector and returns an
+ *  array of extended [[Element]] objects.
+**/
+
+// Implementation provided by selector engine.
+
+/**
+ *  Prototype.Selector.match(element, expression) -> Boolean
+ *  - element (Element): a DOM element.
+ *  - expression (String): A CSS selector.
+ *
+ *  Tests whether `element` matches the CSS selector.
+**/
+
+// Implementation provided by selector engine.
+
+/**
+ *  Prototype.Selector.filter(elements, expression) -> [Element...]
+ *  - elements (Enumerable): a collection of DOM elements.
+ *  - expression (String): A CSS selector.
+ *
+ *  Filters the given collection of elements with `expression` and returns an
+ *  array of extended [[Element]] objects.
+ *
+ *  The only nodes returned will be those that match the given CSS selector.
+**/
+
+// Implementation provided by selector engine.
+