[BUGFIX release] Deprecate immediateObserver

* Ember.immediateObserver was already deprecated, but it's prototype
  extension counterpart wasn't. It's not used internally at all.

* Improve beforeObserver deprecations.

* I had to improve `Ember.deprecateFunc` to accept an options object

packages/ember-debug/lib/main.js

@@ -188,15 +188,25 @@ Ember.deprecate = function(message, test, options) {
 
   @method deprecateFunc
   @param {String} message A description of the deprecation.
+  @param {Object} [options] The options object for Ember.deprecate.
   @param {Function} func The new function called to replace its deprecated counterpart.
   @return {Function} a new function that wrapped the original function with a deprecation warning
   @private
 */
-Ember.deprecateFunc = function(message, func) {
-  return function() {
-    Ember.deprecate(message);
-    return func.apply(this, arguments);
-  };
+Ember.deprecateFunc = function(...args) {
+  if (args.length === 3) {
+    let [message, options, func] = args;
+    return function() {
+      Ember.deprecate(message, false, options);
+      return func.call(this, arguments);
+    };
+  } else {
+    let [message, func] = args;
+    return function() {
+      Ember.deprecate(message);
+      return func.apply(this, arguments);
+    };
+  }
 };
 
 

packages/ember-metal/lib/main.js

@@ -173,7 +173,7 @@ import {
   Mixin,
   aliasMethod,
   _beforeObserver,
-  immediateObserver,
+  _immediateObserver,
   mixin,
   observer,
   required
@@ -310,20 +310,20 @@ Ember.cacheFor = cacheFor;
 Ember.addObserver = addObserver;
 Ember.observersFor = observersFor;
 Ember.removeObserver = removeObserver;
-Ember.addBeforeObserver = Ember.deprecateFunc('Ember.addBeforeObserver is deprecated and will be removed in the near future. See http://emberjs.com/deprecations/v1.x/#toc_beforeobserver', _addBeforeObserver);
+Ember.addBeforeObserver = Ember.deprecateFunc('Ember.addBeforeObserver is deprecated and will be removed in the near future.', { url: 'http://emberjs.com/deprecations/v1.x/#toc_beforeobserver' }, _addBeforeObserver);
 Ember._suspendBeforeObserver = _suspendBeforeObserver;
 Ember._suspendBeforeObservers = _suspendBeforeObservers;
 Ember._suspendObserver = _suspendObserver;
 Ember._suspendObservers = _suspendObservers;
-Ember.beforeObserversFor = Ember.deprecateFunc('Ember.beforeObserversFor is deprecated and will be removed in the near future. See http://emberjs.com/deprecations/v1.x/#toc_beforeobserver', _beforeObserversFor);
-Ember.removeBeforeObserver = Ember.deprecateFunc('Ember.removeBeforeObserver is deprecated and will be removed in the near future. See http://emberjs.com/deprecations/v1.x/#toc_beforeobserver', _removeBeforeObserver);
+Ember.beforeObserversFor = Ember.deprecateFunc('Ember.beforeObserversFor is deprecated and will be removed in the near future.', { url: 'http://emberjs.com/deprecations/v1.x/#toc_beforeobserver' }, _beforeObserversFor);
+Ember.removeBeforeObserver = Ember.deprecateFunc('Ember.removeBeforeObserver is deprecated and will be removed in the near future.', { url: 'http://emberjs.com/deprecations/v1.x/#toc_beforeobserver' }, _removeBeforeObserver);
 
 Ember.IS_BINDING = IS_BINDING;
 Ember.required = required;
 Ember.aliasMethod = aliasMethod;
 Ember.observer = observer;
-Ember.immediateObserver = immediateObserver;
-Ember.beforeObserver = Ember.deprecateFunc('Ember.beforeObserver is deprecated and will be removed in the near future. See http://emberjs.com/deprecations/v1.x/#toc_beforeobserver', _beforeObserver);
+Ember.immediateObserver = _immediateObserver;
+Ember.beforeObserver = Ember.deprecateFunc('Ember.beforeObserver is deprecated and will be removed in the near future.', { url: 'http://emberjs.com/deprecations/v1.x/#toc_beforeobserver' }, _beforeObserver);
 Ember.mixin = mixin;
 Ember.Mixin = Mixin;
 

packages/ember-metal/lib/mixin.js

@@ -853,7 +853,7 @@ export function observer(...args) {
   @return func
   @private
 */
-export function immediateObserver() {
+export function _immediateObserver() {
   Ember.deprecate('Usage of `Ember.immediateObserver` is deprecated, use `Ember.observer` instead.');
 
   for (var i=0, l=arguments.length; i<l; i++) {

packages/ember-metal/tests/observer_test.js

@@ -22,7 +22,7 @@ import {
   mixin,
   observer,
   _beforeObserver,
-  immediateObserver
+  _immediateObserver
 } from 'ember-metal/mixin';
 import run from 'ember-metal/run_loop';
 import {
@@ -1062,7 +1062,7 @@ testBoth('immediate observers should fire synchronously', function(get, set) {
   // trigger deferred behavior
   run(function() {
     mixin = Mixin.create({
-      fooDidChange: immediateObserver('foo', function() {
+      fooDidChange: _immediateObserver('foo', function() {
         observerCalled++;
         equal(get(this, 'foo'), 'barbaz', 'newly set value is immediately available');
       })
@@ -1094,12 +1094,14 @@ if (Ember.EXTEND_PROTOTYPES) {
     // explicitly create a run loop so we do not inadvertently
     // trigger deferred behavior
     run(function() {
-      mixin = Mixin.create({
-        fooDidChange: function() {
-          observerCalled++;
-          equal(get(this, 'foo'), 'barbaz', 'newly set value is immediately available');
-        }.observesImmediately('{foo,bar}')
-      });
+      expectDeprecation(function() {
+        mixin = Mixin.create({
+          fooDidChange: function() {
+            observerCalled++;
+            equal(get(this, 'foo'), 'barbaz', 'newly set value is immediately available');
+          }.observesImmediately('{foo,bar}')
+        });
+      }, /Function#observesImmediately is deprecated. Use Function#observes instead/);
 
       mixin.apply(obj);
 
@@ -1128,7 +1130,7 @@ testBoth('immediate observers watching multiple properties via brace expansion f
   // trigger deferred behavior
   run(function() {
     mixin = Mixin.create({
-      fooDidChange: immediateObserver('{foo,bar}', function() {
+      fooDidChange: _immediateObserver('{foo,bar}', function() {
         observerCalled++;
         equal(get(this, 'foo'), 'barbaz', 'newly set value is immediately available');
       })
@@ -1153,7 +1155,7 @@ testBoth('immediate observers watching multiple properties via brace expansion f
 testBoth('immediate observers are for internal properties only', function(get, set) {
   expectDeprecation(/Usage of `Ember.immediateObserver` is deprecated, use `Ember.observer` instead./);
   expectAssertion(function() {
-    immediateObserver('foo.bar', function() { return this; });
+    _immediateObserver('foo.bar', function() { return this; });
   }, 'Immediate observers must observe internal properties only, not properties on other objects.');
 });
 

packages/ember-runtime/lib/ext/function.js

@@ -96,8 +96,7 @@ if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.Function) {
     });
     ```
 
-    In the future this method may become asynchronous. If you want to ensure
-    synchronous behavior, use `observesImmediately`.
+    In the future this method may become asynchronous.
 
     See `Ember.observer`.
 
@@ -110,6 +109,21 @@ if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.Function) {
     return observer.apply(this, args);
   };
 
+
+  FunctionPrototype._observesImmediately = function () {
+    Ember.assert('Immediate observers must observe internal properties only, ' +
+                 'not properties on other objects.', function checkIsInternalProperty() {
+      for (var i = 0, l = arguments.length; i < l; i++) {
+        if (arguments[i].indexOf('.') !== -1) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    // observes handles property expansion
+    return this.observes(...arguments);
+  };
   /**
     The `observesImmediately` extension of Javascript's Function prototype is
     available when `Ember.EXTEND_PROTOTYPES` or
@@ -134,22 +148,10 @@ if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.Function) {
 
     @method observesImmediately
     @for Function
+    @deprecated
     @private
   */
-  FunctionPrototype.observesImmediately = function () {
-    Ember.assert('Immediate observers must observe internal properties only, ' +
-                 'not properties on other objects.', function checkIsInternalProperty() {
-      for (var i = 0, l = arguments.length; i < l; i++) {
-        if (arguments[i].indexOf('.') !== -1) {
-          return false;
-        }
-      }
-      return true;
-    });
-
-    // observes handles property expansion
-    return this.observes(...arguments);
-  };
+  FunctionPrototype.observesImmediately = Ember.deprecateFunc('Function#observesImmediately is deprecated. Use Function#observes instead', FunctionPrototype._observesImmediately);
 
   /**
     The `observesBefore` extension of Javascript's Function prototype is