docs(*): add deprecation notice for angular.lowercase/uppercase

wesleycho · Narretz · commit 4059600d205a · 2016-11-28T18:50:36.000+01:00
Closes angular#15441 Closes angular#14316
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2028,6 +2028,8 @@ This version of AngularJS is problematic due to a issue during its release. Plea
 
 - The `ngTouch` module's `ngClick` directive has been deprecated and disabled by default. See the breaking
 changes section for more information
+- The `angular.lowercase` and `angular.uppercase` functions have been deprecated and will be removed
+in version 1.7.0. It is recommended to use [String.prototype.toLowerCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) and [String.prototype.toUpperCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) functions instead.
 
 ## Bug Fixes
 
diff --git a/docs/content/guide/migration.ngdoc b/docs/content/guide/migration.ngdoc
@@ -1274,6 +1274,11 @@ and was not consistent with other filters (e.g. `filter`).
 Objects considered array-like include: arrays, array subclasses, strings, NodeLists,
 jqLite/jQuery collections
 
+#### Helper Functions:
+
+The {@link angular.lowercase `angular.lowercase`} and {@link angular.uppercase `angular.uppercase`} functions have been **deprecated** and will be removed
+in version 1.7.0. It is recommended to use [String.prototype.toLowerCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) and [String.prototype.toUpperCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) functions instead.
+
 
 ### ngAria
 
diff --git a/src/Angular.js b/src/Angular.js
@@ -122,9 +122,41 @@ var REGEX_STRING_REGEXP = /^\/(.+)\/([a-z]*)$/;
 // This is used so that it's possible for internal tests to create mock ValidityStates.
 var VALIDITY_STATE_PROPERTY = 'validity';
 
+
 var hasOwnProperty = Object.prototype.hasOwnProperty;
 
+/**
+ * @ngdoc function
+ * @name angular.lowercase
+ * @module ng
+ * @kind function
+ *
+ * @deprecated
+ * sinceVersion="1.5.0"
+ * removeVersion="1.7.0"
+ * Use [String.prototype.toLowerCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) instead.
+ *
+ * @description Converts the specified string to lowercase.
+ * @param {string} string String to be converted to lowercase.
+ * @returns {string} Lowercased string.
+ */
 var lowercase = function(string) {return isString(string) ? string.toLowerCase() : string;};
+
+/**
+ * @ngdoc function
+ * @name angular.uppercase
+ * @module ng
+ * @kind function
+ *
+ * @deprecated
+ * sinceVersion="1.5.0"
+ * removeVersion="1.7.0"
+ * Use [String.prototype.toUpperCase](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) instead.
+ *
+ * @description Converts the specified string to uppercase.
+ * @param {string} string String to be converted to uppercase.
+ * @returns {string} Uppercased string.
+ */
 var uppercase = function(string) {return isString(string) ? string.toUpperCase() : string;};
 
 
