From 798a367a3d761f71db5ca96f5bbe82446d0de8a9 Mon Sep 17 00:00:00 2001
From: tjcrowder <tj@crowdersoftware.com>
Date: Mon, 7 Sep 2009 12:20:55 +0100
Subject: [PATCH] doc: port old Array#flatten docs and clarify

---
 src/lang/array.js | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/lang/array.js b/src/lang/array.js
index ae463bf..980b6b7 100644
--- a/src/lang/array.js
+++ b/src/lang/array.js
@@ -185,11 +185,20 @@ Array.from = $A;
 
   /**
    *  Array#flatten() -> Array
-   *  Returns a "flat" (one-dimensional) version of the array.
    *
-   *  Nested arrays are recursively injected "inline." This can prove very
+   *  Returns a flattened (one-dimensional) copy of the array, leaving
+   *  the original array unchanged.
+   *
+   *  Nested arrays are recursively injected inline. This can prove very
    *  useful when handling the results of a recursive collection algorithm,
    *  for instance.
+   *
+   *  ### Example
+   *
+   *      var a = ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]];
+   *      var b = a.flatten();
+   *      // a -> ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]]
+   *      // b -> ['frank', 'bob', 'lisa', 'jill', 'tom', 'sally']
   **/
   function flatten() {
     return this.inject([], function(array, value) {