Update API docs for BelongsToReference #4639
Conversation
| @@ -5,6 +5,16 @@ import Reference from './reference'; | |||
| import isEnabled from 'ember-data/-private/features'; | |||
| import { assertPolymorphicType, deprecate } from "ember-data/-private/debug"; | |||
|
|
|||
|
|
|||
| /** | |||
| An BelongsToReference is a low level API that allows users and | |||
| /** | ||
| The link Ember Data will use to fetch or reload this belongs-to | ||
| relationship. Together, the `type()` and `id()` methods form a | ||
| composite key for the identity map. |
There was a problem hiding this comment.
Remove this second sentence.
|
|
||
| @method push | ||
| @param {Object|Promise} objectOrPromise a promise that resolves to a JSONAPI document object describing the new value of this relationship. | ||
| @return {Object} The meta information for the belongs-oo relationship. |
There was a problem hiding this comment.
This should say push returns the record.
| `value()` on a reference does not trigger a fetch if the async | ||
| relationship is not yet loaded. If the relationship is not loaded | ||
| it will always return `null`. If the relationship is already loaded | ||
| this method does not trigger a new load. |
There was a problem hiding this comment.
This is copy and pasted from the value docs above.
bmac
force-pushed
the
doc-belongs-to-reference
branch
from
a5f89b1 to
cfd95b1
Compare
| @@ -63,6 +253,50 @@ BelongsToReference.prototype.push = function(objectOrPromise) { | |||
| }); | |||
| }; | |||
|
|
|||
| /** | |||
| `value()` sycronously returns the current value of the belongs-to | |||
There was a problem hiding this comment.
typo: s/sycronously/synchronously/
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| var userRef = blog.belongsTo('user'); | ||
|
|
||
| // provide data for reference | ||
| userRef.push({ |
There was a problem hiding this comment.
this needs to be a JSON-API doc of the form { data: { ... } }
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| userRef.value(); // null | ||
|
|
||
| // provide data for reference | ||
| userRef.push({ |
There was a problem hiding this comment.
this needs to be a JSON-API doc of the form { data: { ... } }
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| user: DS.belongsTo({ async: true }) | ||
| }); | ||
|
|
||
| var blog = store.push({ |
There was a problem hiding this comment.
not a valid format for store.push
| /** | ||
| The `id` of the record that this reference refers to. Together, the | ||
| `type()` and `id()` methods form a composite key for the identity | ||
| map. This can be used to access the id of an asycn relationship |
bmac
force-pushed
the
doc-belongs-to-reference
branch
from
cfd95b1 to
e31089f
Compare
|
@pangratz I've updated this pr to address your comments. |
| related: { | ||
| href: '/articles/1/author', | ||
| meta: { | ||
| count: 10 |
There was a problem hiding this comment.
Tiny nitpick: not sure if this is the best meta value for a single resource 🤔 . But then of course I don't have a better suggestion 😔 single record meta data is hard 😄
Maybe lastUpdated?
bmac
force-pushed
the
doc-belongs-to-reference
branch
from
e31089f to
ff0cbd8
Compare
|
Thanks again @bmac! |
cc @pangratz