From 00ebde59a200be67af1a1a8c201852a64eb72b98 Mon Sep 17 00:00:00 2001
From: tjcrowder <tj@crowdersoftware.com>
Date: Thu, 10 Sep 2009 14:55:12 +0100
Subject: [PATCH] doc: Merged old docs for Hash#each.

---
 src/lang/hash.js | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/src/lang/hash.js b/src/lang/hash.js
index 6844692..4e51108 100644
--- a/src/lang/hash.js
+++ b/src/lang/hash.js
@@ -41,6 +41,45 @@ var Hash = Class.create(Enumerable, (function() {
     this._object = Object.isHash(object) ? object.toObject() : Object.clone(object);
   }
 
+  // Docs for #each even though technically it's implemented by Enumerable
+  /**
+   *  Hash#each(iterator[, context]) -> Hash
+   *  - iterator (Function): A function that expects each item in the `Hash`
+   *    as the first argument and a numerical index as the second.
+   *  - context (Object): The scope in which to call `iterator`. Determines what
+   *    `this` means inside `iterator`.
+   *
+   *  Iterates over the name/value pairs in the hash.
+   *
+   *  This is actually just the [[Enumerable#each #each]] method from the
+   *  mixed-in [[Enumerable]] module. It is documented here to describe the
+   *  structure of the elements passed to the iterator and the order of
+   *  iteration.
+   *
+   *  The iterator's first argument (the "item") is an object with two
+   *  properties:
+   *
+   *  - `key`: the key name as a `String`
+   *  - `value`: the corresponding value (which may be `undefined`)
+   *
+   *  The order of iteration is implementation-dependent, as it relies on
+   *  the order of the native `for..in` loop. Although most modern
+   *  implementations exhibit *ordered* behavior, this is not standardized and
+   *  may not always be the case, and so cannot be relied upon.
+   *
+   *  ### Example
+   *
+   *      var h = $H({version: 1.6, author: 'The Core Team'});
+   *
+   *      h.each(function(pair) {
+   *        alert(pair.key + ' = "' + pair.value + '"');
+   *      });
+   *      // Alerts 'version = "1.6"' and 'author = "The Core Team"'
+   *      // -or-
+   *      // Alerts 'author = "The Core Team"' and 'version = "1.6"'
+  **/
+
+  // Our _internal_ each
   function _each(iterator) {
     for (var key in this._object) {
       var value = this._object[key], pair = [key, value];