@@ -783,7 +783,9 @@ function arrayRemove(array, value) {
783
783
* @kind function
784
784
*
785
785
* @description
786
- * Creates a deep copy of `source`, which should be an object or an array.
786
+ * Creates a deep copy of `source`, which should be an object or an array. This functions is used
787
+ * internally, mostly in the change-detection code. It is not intended as an all-purpose copy
788
+ * function, and has several limitations (see below).
787
789
*
788
790
* * If no destination is supplied, a copy of the object or array is created.
789
791
* * If a destination is provided, all of its elements (for arrays) or properties (for objects)
@@ -800,9 +802,22 @@ function arrayRemove(array, value) {
800
802
*
801
803
* <div class="alert alert-warning">
802
804
* `angular.copy` does not check if destination and source are of the same type. It's the
803
- * developers responsibility to make sure they are compatible.
805
+ * developer's responsibility to make sure they are compatible.
804
806
* </div>
805
807
*
808
+ * @knownIssue
809
+ * This is a non-exhaustive list of object types / features that are not handled correctly by
810
+ * `angular.copy`. Note that since this functions is used by the change detection code, this
811
+ * means binding or watching objects of these types (or that include these types) might not work
812
+ * correctly.
813
+ * - [`ImageData`](https://developer.mozilla.org/docs/Web/API/File)
814
+ * - [`Map`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map)
815
+ * - [`ImageData`](https://developer.mozilla.org/docs/Web/API/ImageData)
816
+ * - [`MediaStream`](https://developer.mozilla.org/docs/Web/API/MediaStream)
817
+ * - [`WeakMap`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
818
+ * - ['getter'](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)/
819
+ * [`setter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)`
820
+ *
806
821
* @param {* } source The source that will be used to make a copy. Can be any type, including
807
822
* primitives, `null`, and `undefined`.
808
823
* @param {(Object|Array)= } destination Destination into which the source is copied. If provided,
0 commit comments