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

---
 src/dom/dom.js | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/dom/dom.js b/src/dom/dom.js
index 9870c52..3b0f8d8 100644
--- a/src/dom/dom.js
+++ b/src/dom/dom.js
@@ -646,7 +646,30 @@ Element.Methods = {
    *  - selector (String): A CSS selector.
    *
    *  Finds all siblings of the current element that match the given
-   *  selector(s).
+   *  selector(s). If you provide multiple selectors, siblings matching *any*
+   *  of the selectors are included. If a sibling matches multiple selectors,
+   *  it is only included once. The order of the returned array is not defined.
+   *
+   *  ##### Example
+   *
+   *  Assuming this list:
+   *
+   *      language: html
+   *      <ul id="cities">
+   *        <li class="us" id="nyc">New York</li>
+   *        <li class="uk" id="lon">London</li>
+   *        <li class="us" id="chi">Chicago</li>
+   *        <li class="jp" id="tok">Tokyo</li>
+   *        <li class="us" id="la">Los Angeles</li>
+   *        <li class="us" id="aus">Austin</li>
+   *      </ul>
+   *
+   *  Then:
+   *
+   *      $('nyc').adjacent('li.us');
+   *      // -> [li#chi, li#la, li#aus]
+   *      $('nyc').adjacent('li.uk', 'li.jp');
+   *      // -> [li#lon, li#tok]
   **/
   adjacent: function(element) {
     var args = Array.prototype.slice.call(arguments, 1);