docs(Attributes): add missing documentation for $observe method

- Add proper ngdoc annotations to existing $observe documentation
- Add link to directive guide for usage example of $observe
- Add note about $observe function parameter signature

Closes #3957

1 files changed, 11 insertions, 2 deletions

diff --git a/src/ng/compile.js b/src/ng/compile.js
index 30d048d4..5cd220ef 100644
--- a/src/ng/compile.js
+++ b/src/ng/compile.js
@@ -319,12 +319,21 @@ function $CompileProvider($provide) {
 
 
       /**
+       * @ngdoc function
+       * @name ng.$compile.directive.Attributes#$observe
+       * @methodOf ng.$compile.directive.Attributes
+       * @function
+       *
+       * @description
        * Observe an interpolated attribute.
        * The observer will never be called, if given attribute is not interpolated.
+       * The interpolated value of the attribute is passed to the observer function.
        *
        * @param {string} key Normalized key. (ie ngAttribute) .
-       * @param {function(*)} fn Function that will be called whenever the attribute value changes.
-       * @returns {function(*)} the `fn` Function passed in.
+       * @param {function(interpolatedValue)} fn Function that will be called whenever
+                the interpolated value of the attribute changes.
+       *        See the {@link guide/directive#Attributes Directives} guide for more info.
+       * @returns {function()} the `fn` parameter.
        */
       $observe: function(key, fn) {
         var attrs = this,