Merge pull request #16 from dknutsen/options-and-yuidoc

Options and yuidoc, closes #13 and #15

addon/components/needs-async.js

@@ -1,6 +1,30 @@
 import Component from '@ember/component';
 import layout from '../templates/components/needs-async';
 
+/**
+  Usage:
+
+  ```hbs
+    <NeedsAsync @needs=(find-record 'user' '1') as |States|>
+      <States.loading>
+        <!-- render a loading state here -->
+      </States.loading>
+      <States.loaded as |user|>
+        <!-- render whatever needs 'user' here -->
+      </States.loaded>
+      <States.error as |error|>
+        <!-- render an error state here optionally using 'error' -->
+      </States.error>
+    </NeedsAsync>
+  ```
+
+  @class NeedsAsync
+  @yield {Hash} States
+  @yield {TaskInstance} States.taskInstance an Ember Concurrency TaskInstance
+  @yield {Component} States.loading a component that renders its block if the task instance is still loading
+  @yield {Component} States.loaded a component that renders its block and yields the task value once the task is done loading
+  @yield {Component} States.error a component that renders its block and yields an error if the tak encountered an error
+*/
 export default Component.extend({
   layout,
   tagName: '',

addon/helpers/async-all.js

@@ -1,6 +1,20 @@
 import Helper from '@ember/component/helper';
 import { all, task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{async-all (array
+      (find-record "user" "1")
+      (find-record "user" "2")
+    )}}
+  ```
+
+  @function async-all
+  @param {array} taskInstances an array of Ember Concurrency task instances
+  @return {TaskInstance} a TaskInstance that resolves to an array of TaskInstance results
+*/
 export default Helper.extend({
   asyncAllTask: task(function * (tasks) {
     return yield all(tasks);

addon/helpers/async-hash.js

@@ -1,6 +1,20 @@
 import Helper from '@ember/component/helper';
 import { hash, task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{async-hash (hash
+      foo=(find-record "user" "1")
+      bar=(find-record "user" "2")
+    )}}
+  ```
+
+  @function async-hash
+  @param {array} taskInstances an array of Ember Concurrency task instances
+  @return {TaskInstance} a TaskInstance that resolves to a hash of TaskInstance results
+*/
 export default Helper.extend({
   asyncHashTask: task(function * (tasks) {
     return yield hash(tasks);

addon/helpers/belongs-to.js

@@ -1,6 +1,18 @@
 import Helper from '@ember/component/helper';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{belongs-to user "company"}}
+  ```
+
+  @function belongs-to
+  @param {DS.Model} model the model to fetch the belongs-to relationship from
+  @param {string} relationship the name of the relationship to fetch
+  @return {TaskInstance} a TaskInstance that resolves to a DS.Model
+*/
 export default Helper.extend({
   belongsToTask: task(function * (model, relationship) {
     return yield model.belongsTo(relationship).load();

addon/helpers/find-all.js

@@ -2,12 +2,24 @@ import Helper from '@ember/component/helper';
 import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{find-all "user" (hash include="company")}}
+  ```
+
+  @function find-all
+  @param {string} modelType the model type to request
+  @param {object} options (optional) options to pass to the store.findAll method
+  @return {TaskInstance} a TaskInstance that resolves to a DS.RecordArray
+*/
 export default Helper.extend({
   store: service(),
-  findAllTask: task(function * (modelType) {
-    return yield this.store.findAll(modelType);
+  findAllTask: task(function * (modelType, options) {
+    return yield this.store.findAll(modelType, options);
   }),
-  compute([modelType/*, ...rest*/]/*, hash*/) {
-    return this.findAllTask.perform(modelType);
+  compute([modelType, options/*, ...rest*/]/*, hash*/) {
+    return this.findAllTask.perform(modelType, options);
   }
 });

addon/helpers/find-record.js

@@ -2,13 +2,26 @@ import Helper from '@ember/component/helper';
 import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{find-record "user" "1" (hash include="company")}}
+  ```
+
+  @function find-all
+  @param {string} modelType the model type to request
+  @param {string} id the id of the model to request
+  @param {object} options (optional) options to pass to the store.findRecord method
+  @return {Promise} a promise that resolves to a DS.Model
+*/
 export default Helper.extend({
   store: service(),
-  findRecordTask: task(function * (modelType, id) {
-    return yield this.store.findRecord(modelType, id);
+  findRecordTask: task(function * (modelType, id, options) {
+    return yield this.store.findRecord(modelType, id, options);
   }),
-  compute([modelType, id/*, ...rest*/]/*, hash*/) {
+  compute([modelType, id, options/*, ...rest*/]/*, hash*/) {
     if(!id) return null;
-    return this.findRecordTask.perform(modelType, id);
+    return this.findRecordTask.perform(modelType, id, options);
   }
 });

addon/helpers/has-many.js

@@ -1,6 +1,18 @@
 import Helper from '@ember/component/helper';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{has-many company "employees"}}
+  ```
+
+  @function has-many
+  @param {DS.Model} model the model to fetch the has-many relationship from
+  @param {string} relationship the name of the relationship to fetch
+  @return {TaskInstance} a TaskInstance that resolves to a DS.RecordArray
+*/
 export default Helper.extend({
   hasManyTask: task(function * (model, relationship) {
     return yield model.hasMany(relationship).load();

addon/helpers/peek-all.js

@@ -2,6 +2,17 @@ import Helper from '@ember/component/helper';
 import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{peek-all "user"}}
+  ```
+
+  @function peek-all
+  @param {string} modelType the model type to request
+  @return {TaskInstance} a TaskInstance that resolves immediately to a DS.RecordArray
+*/
 export default Helper.extend({
   store: service(),
   peekAllTask: task(function * (modelType) {

addon/helpers/peek-record.js

@@ -2,6 +2,18 @@ import Helper from '@ember/component/helper';
 import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{peek-record "user" "1"}}
+  ```
+
+  @function peek-record
+  @param {string} modelType the model type to request
+  @param {string} id the id of the model to fetch from the store
+  @return {TaskInstance} a TaskInstance that resolves immediately to a DS.Model
+*/
 export default Helper.extend({
   store: service(),
   peekRecordTask: task(function * (modelType, id) {

addon/helpers/query.js

@@ -2,6 +2,18 @@ import Helper from '@ember/component/helper';
 import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
+/**
+  Usage:
+
+  ```hbs
+    {{query "user" (hash lastName="smith" page=2)}}
+  ```
+
+  @function query
+  @param {string} modelType the model type to request
+  @param {object} query the hash that includes all params for the query
+  @return {TaskInstance} a TaskInstance that resolves to a DS.RecordArray
+*/
 export default Helper.extend({
   store: service(),
   queryTask: task(function * (modelType, hash) {