1 files changed, 52 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md b/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md
new file mode 100644
index 0000000..0906b0d
--- /dev/null
+++ b/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md
@@ -0,0 +1,52 @@
+The `es5` module provides shim layer to a versions of Firefox that do not yet
+implement certain EcmaScript 5 features.
+
+For more information on EcmaScript 5:
+
+* The new APIs are described in the official [ES5 specification][].
+* A good [introduction][] to the new APIs by John Resig.
+* A Google tech talk on [changes to JavaScript][].
+
+**There is no need to `require` this module** since it gets preloaded into
+all sandboxes automatically.
+
+Usage of new ES5 API's is encouraged, but since not everything can be
+provided to all the versions of firefox, there are few things to be aware of:
+
+`Object.freeze`, `Object.seal`, `Object.preventExtensions` does not really
+prevents any mutations. One thing it guarantees though, `Object.isFrozen`,
+`Object.isSealed`, `Object.isExtensible` checks will behave as defined in
+specification.
+
+`Object.defineProperty` is only partially compliant with the specification:
+
+- Non configurable properties will be created as configurable ones.
+
+- Instead of non-writable properties getters and setters will be defined,
+but `Object.getOwnPropertyDescriptor` will still behave as expected
+(will return property descriptor for non-writable property not a getter)
+
+- Defining properties using ES5 functions will break your
+     [custom iterators][] if you have any. Think twice before employing
+     custom iterators, because in most cases you can just make properties
+     non enumerable. If you really need to have a custom iterator, add it
+     after running ES5 functions and don't ignore previous iterators.
+     For example:
+
+         let object = Object.create({}, {
+           myField: { value: 6 }
+         });
+         object.__iterator__ = (function(original) {
+           return function myIterator() {
+             this.__iterator__ = original;
+             for (let key in this) {
+               // your logic here
+             }
+             this.__iterator__ = myIterator;
+           }
+         })(object.__iterator__);
+
+[custom iterators]:https://developer.mozilla.org/en/New_in_JavaScript_1.7#Iterators
+[ES5 specification]:http://www.ecmascript.org/docs/tc39-2009-043.pdf
+[introduction]:http://ejohn.org/blog/ecmascript-5-objects-and-properties/
+[changes to JavaScript]:http://www.youtube.com/watch?v=Kq4FpMe6cRs