Merge pull request #254 from ember-learn/add-computed-property-modifi…

…er-deprecations

[FEAT] Adds the various ComputedProperty modifier deprecations

content/ember/v3/computed-property-override.md

@@ -0,0 +1,58 @@
+---
+id: computed-property.override
+title: Computed Property Overridability
+until: '4.0.0'
+since: '3.8'
+---
+
+Ember's computed properties are overridable by default if no setter is defined:
+
+```js
+const Person = EmberObject.extend({
+  firstName: 'Diana',
+  lastName: 'Prince',
+
+  fullName: computed('firstName', 'lastName', function() {
+    return `${this.firstName} ${this.lastName}`;
+  })
+});
+
+let person = Person.create();
+person.fullName; // Diana Prince
+
+person.set('fullName', 'Carol Danvers');
+
+person.set('firstName', 'Bruce');
+person.set('lastName', 'Wayne');
+
+
+person.fullName; // Carol Danvers
+```
+
+This behavior is bug prone and has been deprecated. `readOnly()`, the modifier
+that prevents this behavior, will be deprecated once overridability has been
+removed.
+
+If you still need this behavior, you can create a setter which accomplishes this
+manually:
+
+```js
+const Person = EmberObject.extend({
+  firstName: 'Diana',
+  lastName: 'Prince',
+
+  fullName: computed('firstName', 'lastName', {
+    get() {
+      if (this._fullName) {
+        return this._fullName;
+      }
+
+      return `${this.firstName} ${this.lastName}`;
+    },
+
+    set(key, value) {
+      this._fullName = value;
+    }
+  })
+});
+```

content/ember/v3/computed-property-property.md

@@ -0,0 +1,52 @@
+---
+id: computed-property.property
+title: Computed Property `.property()` Modifier
+until: '4.0.0'
+since: '3.8'
+---
+
+`.property()` is a modifier that adds additional property dependencies to an
+existing computed property:
+
+```js
+const Person = EmberObject.extend({
+  fullName: computed(function() {
+    return `${this.firstName} ${this.lastName}`;
+  }).property('firstName', 'lastName')
+});
+```
+
+To update, move the dependencies to the main computed property definition:
+
+```js
+const Person = EmberObject.extend({
+  fullName: computed('firstName', 'lastName', function() {
+    return `${this.firstName} ${this.lastName}`;
+  })
+});
+```
+
+In the case of the `filter`, `map`, and `sort` computed property macros, it was
+previously possible to need to add dependencies because they weren't available
+in the public APIs of those macros. An optional second parameter has now been
+added to these macros which is an array of additional dependent keys, allowing
+you to pass these dependencies to them:
+
+```js
+// before
+const Person = EmberObject.extend({
+  friendNames: map('friends', function(friend) {
+    return friend[this.get('nameKey')];
+  }).property('nameKey')
+});
+
+// after
+const Person = EmberObject.extend({
+  friendNames: map('friends', ['nameKey'], function(friend) {
+    return friend[this.get('nameKey')];
+  })
+});
+```
+
+Custom computed property macros that encounter this issue should also be
+refactored to be able to receive the additional keys as parameters.

content/ember/v3/computed-property-volatile.md

@@ -0,0 +1,36 @@
+---
+id: computed-property.volatile
+title: Computed Property Volatility
+until: '4.0.0'
+since: '3.8'
+---
+
+`.volatile()` is a computed property modifier which makes a computed property
+recalculate every time it is accessed, instead of caching. It also prevents
+property notifications from ever occuring on the property, which is generally
+not the behavior that developers are after. Volatile properties are usually used
+to simulate the behavior of native getters, which means that they would
+otherwise behave like normal properties.
+
+To update, consider upgrading to native class syntax and using native getters
+directly instead:
+
+Before:
+
+```js
+const Person = EmberObject.extend({
+  fullName: computed(function() {
+    return `${this.firstName} ${this.lastName}`;
+  }).volatile()
+});
+```
+
+After:
+
+```js
+class Person {
+  get fullName() {
+    return `${this.firstName} ${this.lastName}`;
+  }
+}
+```