doc: Merged/updated old docs for Element.ancestors.

2009-10-09 14:48:47 +01:00 · 2009-10-09 14:48:47 +01:00 · e3c89c08c6
parent 402a2d408e
commit e3c89c08c6
1 changed files with 28 additions and 2 deletions
--- a/src/dom/dom.js
+++ b/src/dom/dom.js
@ -470,8 +470,34 @@ Element.Methods = {
  /**
   *  Element.ancestors(@element) -> [Element...]
   *
-   *  Collects all of `element`'s ancestors and returns them as an array of
-   *  elements.
+   *  Collects all of `element`'s ancestor elements and returns them as an
+   *  array of extended elements.
+   *
+   *  The returned array's first element is `element`'s direct ancestor (its
+   *  `parentNode`), the second one is its grandparent, and so on until the
+   *  `html` element is reached. `html` will always be the last member of the
+   *  array. Calling `ancestors` on the `html` element will return an empty
+   *  array.
+   *
+   *  ##### Example
+   *
+   *  Assuming:
+   *
+   *      language: html
+   *      <html>
+   *      [...]
+   *        <body>
+   *          <div id="father">
+   *            <div id="kid">
+   *            </div>
+   *          </div>
+   *        </body>
+   *      </html>
+   *
+   *  Then:
+   *
+   *      $('kid').ancestors();
+   *      // -> [div#father, body, html]
  **/
  ancestors: function(element) {
    return Element.recursivelyCollect(element, 'parentNode');