docs for angular.Object and angular.Object.equals

2 files changed, 53 insertions, 0 deletions

diff --git a/src/Angular.js b/src/Angular.js
index 205b91e3..7d6f8502 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -760,6 +760,39 @@ function copy(source, destination){
   return destination;
 }
 
+
+/**
+ * @workInProgress
+ * @ngdoc function
+ * @name angular.Object.equals
+ * @function
+ *
+ * @description
+ * Determines if two objects or value are equivalent.
+ *
+ * To be equivalent, they must pass `==` comparison or be of the same type and have all their
+ * properties pass `==` comparison.
+ *
+ * Supports values types, arrays and objects.
+ *
+ * For objects `function` properties and properties that start with `$` are not considered during
+ * comparisons.
+ *
+ * @param {*} o1 Object or value to compare.
+ * @param {*} o2 Object or value to compare.
+ * @returns {boolean} True if arguments are equal.
+ *
+ * @example
+   Salutation: <input type="text" name="master.salutation" value="Hello" /><br/>
+   Name: <input type="text" name="master.name" value="world"/><br/>
+   <button ng:click="form = master.$copy()">copy</button>
+   <hr/>
+
+   Master is <span ng:hide="master.$equals(form)">NOT</span> same as form.
+
+   <pre>master={{master}}</pre>
+   <pre>form={{form}}</pre>
+ */
 function equals(o1, o2) {
   if (o1 == o2) return true;
   var t1 = typeof o1, t2 = typeof o2, length, key, keySet;
diff --git a/src/apis.js b/src/apis.js
index 250aec84..65070505 100644
--- a/src/apis.js
+++ b/src/apis.js
@@ -11,6 +11,26 @@ var angularGlobal = {
   }
 };
 
+
+/**
+ * @workInProgress
+ * @ngdoc overview
+ * @name angular.Object
+ * @function
+ *
+ * @description
+ * Utility functions for manipulation with JavaScript objects.
+ *
+ * These functions are exposed in two ways:
+ *
+ * - **in angular expressions**: the functions are bound to all objects and augment the Object
+ *   type. The names of these methods are prefixed with `$` character to minimize naming collisions.
+ *   To call a method, invoke the function without the first argument, e.g, `myObject.$foo(param2)`.
+ *
+ * - **in JavaScript code**: the functions don't augment the Object type and must be invoked as
+ *   functions of `angular.Object` as `angular.Object.foo(myObject, param2)`.
+ *
+ */
 var angularCollection = {
   'copy': copy,
   'size': size,