fix dox

Author: Roman Kuznietsov

addon/adapters/base.js

@@ -9,9 +9,7 @@ import LFAdapter from 'ember-localforage-adapter/adapters/localforage';
 import LFSerializer from 'ember-localforage-adapter/serializers/localforage';
 import isObjectEmpty from 'ember-data-offline/utils/is-object-empty';
 /**
-This is an example of usage of Online and Offline mixins.
-It simplifies setup proccess.  By default it use RESTAdapter and LocalForageAdapter,
-but you can use your own adapters that you like.
+A base adapter, that can be used as-is or extended if necessary.
 
 @class BaseAdapter
 @extends DS.RESTAdapter

addon/jobs/localforage.js

@@ -6,14 +6,17 @@ import Ember from 'ember';
 import jobMixin from 'ember-data-offline/mixins/job';
 import persistOffline from 'ember-data-offline/utils/persist-offline';
 /**
+An implementation of a syncronization job for the Localforage storage.
+
 @class Localforage
 @extends Ember.Object
 @uses Job
 @constructor
 **/
 export default Ember.Object.extend(jobMixin, {
   /**
-  Executes task. Before executiong you need to set the method, which should be executed, and the params for method.
+  A method called by default to execute the job.
+  The method to be called as well as it's arguments can be customized.
   @method task
   @return promise {Promise}
   **/
@@ -25,7 +28,7 @@ export default Ember.Object.extend(jobMixin, {
   },
 
   /**
-  Task for saving records offline after findAll operation.
+  Saves the loaded records to the local storage.
   @method findAll
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -34,7 +37,7 @@ export default Ember.Object.extend(jobMixin, {
     persistOffline(this.get('adapter'), store, typeClass, null, 'findAll');
   },
   /**
-  Task for saving record offline after find operation.
+  Saves the loaded record to the local storage.
   @method find
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -45,7 +48,7 @@ export default Ember.Object.extend(jobMixin, {
     persistOffline(adapter, store, typeClass, id, "find");
   },
   /**
-  Task for saving records offline after findQuery operation.
+  Saves the loaded record to the local storage.
   @method findQuery
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -58,7 +61,7 @@ export default Ember.Object.extend(jobMixin, {
   },
 
   /**
-  Task for saving records offline after findMany operation.
+  Saves the loaded records to the local storage.
   @method findMany
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -69,7 +72,7 @@ export default Ember.Object.extend(jobMixin, {
     persistOffline(adapter, store, typeClass, ids, 'findMany');
   },
   /**
-  Task for saving record offline after createRecord operation.
+  Saves the loaded record to the local storage.
 
   @method createRecord
   @param store {DS.Store}
@@ -83,7 +86,7 @@ export default Ember.Object.extend(jobMixin, {
     });
   },
   /**
-  Task for updating record offline after updateRecord operation.
+  Updates the record in the local storage.
 
   @method updateRecord
   @param store {DS.Store}
@@ -97,7 +100,7 @@ export default Ember.Object.extend(jobMixin, {
     });
   },
   /**
-  Task for deleting record offline after deleteRecord operation.
+  Deletes the record from the local storage.
 
   @method deleteRecord
   @param store {DS.Store}

addon/jobs/rest.js

@@ -8,15 +8,16 @@ import { persistOne } from 'ember-data-offline/utils/persist-offline';
 import { eraseOne } from 'ember-data-offline/utils/erase-offline';
 import extractTargetRecordFromPayload from 'ember-data-offline/utils/extract-online';
 /**
-Lightweight online job for pushing the data from online adapter to store and syncing offline data with the data from the store.
+A job that syncronizes the local storage with the backend.
 @class Rest
 @extends Ember.Object
 @uses Job
 @constructor
 **/
 export default Ember.Object.extend(jobMixin, {
   /**
-  Executes task. Before executiong you need to set the method, which should be executed, and the params for method.
+  A method called by default to execute the job.
+  The method to be called as well as it's arguments can be customized.
   @method task
   @return promise {Promise}
   **/
@@ -27,9 +28,7 @@ export default Ember.Object.extend(jobMixin, {
     return this.get('adapter')[this.get('method')].apply(this.get('adapter'), this.get('params'));
   },
   /**
-  Pushes the raw of data from an adapter's findAll method to the store and creates
-  the offline job for syncing offline data with the data from the store.
-  Returns a promise for the resulting payload.
+  Saves the data received from the backend to the local storage.
   @method findAll
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -53,9 +52,7 @@ export default Ember.Object.extend(jobMixin, {
   },
 
   /**
-  Pushes the record form an adapter's find method to the store and creates
-  the offline job for syncing offline data with the data from the store.
-  Returns a promise for the resulting payload.
+  Saves the data received from the backend to the local storage.
   @method find
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -81,9 +78,7 @@ export default Ember.Object.extend(jobMixin, {
   },
 
   /**
-  Pushes the raw of data form an adapter's find method to the store and creates
-  the offline job for syncing offline data with the data from the store.
-  Returns a promise for the resulting payload.
+  Saves the data received from the backend to the local storage.
   @method findQuery
   @param store {DS.Store}
   @param type {DS.Model}
@@ -102,8 +97,7 @@ export default Ember.Object.extend(jobMixin, {
     return adapterResp;
   },
   /**
-  Pushes the raw of data form an adapter's find method into the store and creates
-  the offline job for syncing offline data with the data from the store.
+  Saves the data received from the backend to the local storage.
   @method findMany
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -120,9 +114,8 @@ export default Ember.Object.extend(jobMixin, {
     return adapterResp;
   },
   /**
-  Pushes a newly created record into the store and creates
-  the offline job for saving this record into offline storage.
-  @method findMany
+  Saves the data received from the backend to the local storage.
+  @method createRecord
   @param store {DS.Store}
   @param type {DS.Model}
   @param snapshot {DS.Snapshot}
@@ -147,9 +140,8 @@ export default Ember.Object.extend(jobMixin, {
       .catch(apiHandler);
   },
   /**
-  Calls the updateRecord method on adapter.
-  Returns a promise for the resulting payload.
-  @method findMany
+  Saves the data received from the backend to the local storage.
+  @method updateRecord
   @param store {DS.Store}
   @param type {DS.Model}
   @param snapshot {DS.Snapshot}
@@ -161,9 +153,8 @@ export default Ember.Object.extend(jobMixin, {
     return adapter.updateRecord(store, type, snapshot, fromJob);
   },
   /**
-  Calls the deleteRecord method on adapter.
-  Returns a promise for the resulting payload.
-  @method findMany
+  Removes the deleted record from the local storage.
+  @method deleteRecord
   @param store {DS.Store}
   @param type {DS.Model}
   @param snapshot {DS.Snapshot}

addon/mixins/base.js

@@ -15,7 +15,7 @@ const { Mixin, $, on,  computed, get, isPresent } = Ember;
 **/
 export default Mixin.create({
   /**
-  Shows if adapter is offline.
+  Availability of the backend.
   @property isOffline
   @type {boolean}
   **/
@@ -33,15 +33,16 @@ export default Mixin.create({
   **/
   offlineJob: offlineJob,
   /**
-  The period of time during which record is considered to be not expired.
+  Record cache expiration time. After expiration the record will be requested again
+  rather than fetched from local storage.
   @property recordTTL
   @type {Object}
   **/
   recordTTL: moment.duration(12, 'hours'),
   /**
   Used by adapter to get queue.
 
-  Returns the working queue from an adapter. If there is no queue in adapter then returns queue from passed store.
+  Returns the syncronization job queue of an adapter or a store.
   @private
   @method _workingQueue
   @param store {DS.Store}
@@ -56,8 +57,8 @@ export default Mixin.create({
   },
 
   /**
-  Adds job to queue. If onDemandKey param was passed, then job will be stored as 'onDemand'
-  and will be processed on demand.
+  Adds a job to the queue. If 'onDemandKey' param was passed, the job will be
+  processed on-demand.
 
   @method addToQueue
   @param job {Job} job to add to queue.
@@ -69,10 +70,8 @@ export default Mixin.create({
   },
 
   /**
-  Used by classes which use this class.
-
-  Creates the online job and addes it to queue. If onDemandKey param was passed, then job will be stored as 'onDemand'
-  and will be processed on demand.
+  Creates and adds an online job to the queue. If 'onDemandKey' param was passed, the job will be
+  processed on-demand.
 
   @method createOnlineJob
   @param method {String} the name of method which will be runned by job.
@@ -90,10 +89,8 @@ export default Mixin.create({
     this.addToQueue(job, store, onDemandKey);
   },
   /**
-  Used by classes which use this class.
-
-  Creates the offline job and addes it to queue. If onDemandKey param was passed, then job will be stored as 'onDemand'
-  and will be processed on demand.
+  Creates and adds an offline job to the queue. If 'onDemandKey' param was passed, the job will be
+  processed on-demand.
 
   @method createOfflineJob
   @param method {String} the name of method which will be runned by job.

addon/mixins/job.js

@@ -5,9 +5,9 @@ import Ember from 'ember';
 const { computed, RSVP } = Ember;
 
 /**
-Base class for creating lightweight jobs.
+An abstract job.
 
-Job is an abstract class and is not meant to be used directly. The following classes extend Job:
+Examples:
 {{#crossLink "Localforage"}}{{/crossLink}}
 {{#crossLink "Rest"}}{{/crossLink}}
 
@@ -23,7 +23,7 @@ export default Ember.Mixin.create({
   retryCount: 0,
 
   /**
-  Shows if there are retry attempts.
+  Shows if there are retry attempts left.
   @property needRetry
   @type {boolean}
   **/
@@ -38,7 +38,7 @@ export default Ember.Mixin.create({
   },
 
   /**
-  Called by the Queue to perform the job.
+  Called to perform the job.
   @method perform
   @return {Ember.Promise}
   **/

addon/mixins/offline.js

@@ -9,7 +9,7 @@ import { isExpiredOne, isExpiredMany, isExpiredAll } from 'ember-data-offline/ut
 import { updateMeta } from 'ember-data-offline/utils/meta';
 
 /**
-Ofline mixin redefines all adapter methods for finding, creation, deletion to make request to offline storage.
+Offline mixin redefines all adapter persistance methods to make request to offline storage.
 
 @class Offline
 @extends Ember.Mixin
@@ -31,8 +31,8 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Returns the metadata for a given. Returned metadata consists information about
-  last fetched and last updated time.
+  Returns the metadata for a given model. Returned metadata contains information about
+  latest fetch and update times.
 
   @method metadataForType
   @param typeClass {DS.Model}
@@ -45,9 +45,10 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Overrides the method of an extended adapter (offline). Fetches a JSON array for all of the records for a given type
-  from offline adapter. If fetched records are expired then tries to create online job of fetching the records
-  from online adapter and persisting them offline. Returns a promise for the resulting payload.
+  Overrides the method of an extended adapter (offline). Fetches a JSON array
+  for all of the records for a given type from offline adapter. If fetched
+  records are expired, it tries to create an online job to fetch the records
+  from the online adapter and save them locally.
 
   @method findAll
   @param store {DS.Store}
@@ -73,9 +74,9 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Overrides the method of an extended adapter (offline). Fetches a JSON for a given type and ID
-  from offline adapter. If fetched record is expired then tries to create online job of fetching the record
-  from online adapter and persisting it offline. Returns a promise for the resulting payload.
+  Overrides the method of an extended adapter (offline). Fetches a JSON array for all of the records for a given type
+  from offline adapter. If fetched expired records and then tries to create an online job to fetch the records
+  from the online adapter and save them locally.
   @method find
   @param store {DS.Store}
   @param typeClass {DS.Model}
@@ -102,9 +103,9 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Overrides the method of an extended adapter (offline). Fetches a JSON array for the records that match a particular query
-  from offline adapter. If fetched records are expired then tries to create online job of fetching the records
-  from online adapter and persisting them offline. Returns a promise for the resulting payload.
+  Overrides the method of an extended adapter (offline). Fetches a JSON array for all of the records for a given type
+  from offline adapter. If fetched expired records and then tries to create an online job to fetch the records
+  from the online adapter and save them locally.
 
   @method query
   @param store {DS.Store}
@@ -132,9 +133,9 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Overrides the method of an extended adapter (offline). Fetches a JSON array for  a given type and IDs
-  from offline adapter. If fetched records are expired then tries to create online job of fetching the records
-  from online adapter and persisting them offline. Returns a promise for the resulting payload.
+  Overrides the method of an extended adapter (offline). Fetches a JSON array for all of the records for a given type
+  from offline adapter. If fetched expired records and then tries to create an online job to fetch the records
+  from the online adapter and save them locally.
 
   @method findMany
   @param store {DS.Store}
@@ -165,9 +166,8 @@ export default Ember.Mixin.create(baseMixin, {
   },
 
   /**
-  Called  when a newly created record is saved via the `save` method on a model record instance.
-  If this method was called from Queue(fromJob) then it would create an online job for creation record.
-  Calls the implementation method of parrent offline adapter.
+  Overrides the method of an extended adapter (offline).
+  If tries to create an online job to create the record and save it locally.
   @method createRecord
   @param store {DS.Store}
   @param type {DS.Model}
@@ -190,11 +190,8 @@ export default Ember.Mixin.create(baseMixin, {
     return this._super.apply(this, [store, type, snapshot]);
   },
   /**
-  Called when an existing record is saved
-  via the `save` method on a model record instance.
-
-  If this method was called from Queue(fromJob) then it would create an online job for updating record.
-  Calls the implementation method of parrent offline adapter.
+  Overrides the method of an extended adapter (offline).
+  If tries to create an online job to update the record and save it locally.
   @method updateRecord
   @param store {DS.Store}
   @param type {DS.Model}
@@ -211,9 +208,8 @@ export default Ember.Mixin.create(baseMixin, {
     return this._super.apply(this, [store, type, snapshot]);
   },
   /**
-  Called when a record is deleted.
-  If this method was called from Queue(fromJob) then it would create an online job for deletion record.
-  Calls the implementation method of parrent offline adapter.
+  Overrides the method of an extended adapter (offline).
+  If tries to create an online job to delete the record and remove it locally.
   @method deleteRecord
   @param store {DS.Store}
   @param type {DS.Model}