@@ -783,7 +783,9 @@ function arrayRemove(array, value) {
783783 * @kind function
784784 *
785785 * @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).
787789 *
788790 * * If no destination is supplied, a copy of the object or array is created.
789791 * * If a destination is provided, all of its elements (for arrays) or properties (for objects)
@@ -800,9 +802,22 @@ function arrayRemove(array, value) {
800802 *
801803 * <div class="alert alert-warning">
802804 * `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.
804806 * </div>
805807 *
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+ *
806821 * @param {* } source The source that will be used to make a copy. Can be any type, including
807822 * primitives, `null`, and `undefined`.
808823 * @param {(Object|Array)= } destination Destination into which the source is copied. If provided,
0 commit comments