fix(Angular): deprecate angular.merge

Narretz · web-flow · commit 464dde8bd12d · 2017-06-12T15:59:20.000+02:00
This function has problems with special object types but since it's not used in core, it is not worth implementing fixes for these cases. A general purpose library like lodash (provides `merge`) should be used instead. Closes angular#12653 Closes angular#14941 Closes angular#15180 Closes angular#15992 Closes angular#16036
diff --git a/src/Angular.js b/src/Angular.js
@@ -421,6 +421,20 @@ function extend(dst) {
 * Unlike {@link angular.extend extend()}, `merge()` recursively descends into object properties of source
 * objects, performing a deep copy.
 *
+* @deprecated
+* sinceVersion="1.6.5"
+* This function is deprecated, but will not be removed in the 1.x lifecycle.
+* There are edge cases (see {@link angular.merge#known-issues known issues}) that are not
+* supported by this function. We suggest
+* using [lodash's merge()](https://lodash.com/docs/4.17.4#merge) instead.
+*
+* @knownIssue
+* This is a list of (known) object types that are not handled correctly by this function:
+* - [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)
+* - [`MediaStream`](https://developer.mozilla.org/docs/Web/API/MediaStream)
+* - [`CanvasGradient`](https://developer.mozilla.org/docs/Web/API/CanvasGradient)
+* - AngularJS {@link $rootScope.Scope scopes};
+*
 * @param {Object} dst Destination object.
 * @param {...Object} src Source object(s).
 * @returns {Object} Reference to `dst`.
