Merge pull request #6 from letitia/app-fetcher-docs-edits

saponifi3d · saponifi3d · commit 008d69caedc7 · 2015-02-06T21:29:27.000-08:00
App and Fetcher documentation edits
diff --git a/_app/bootstrapData.md b/_app/bootstrapData.md
@@ -3,4 +3,4 @@ header: bootstrapData
 example: App.bootstrapData(modelMap)
 ---
 
-Generally, invoked in the layout file following the [constructor](#constructor) call.  This will simply invoke the [Fetcher.bootstrapData](/fetcher#bootstrapData) function.
+This is generally invoked in the layout file following the [constructor](#constructor) call.  This will simply call the [Fetcher.bootstrapData](/fetcher#bootstrapData) function.
diff --git a/_app/config.md b/_app/config.md
@@ -6,14 +6,14 @@ example:
 The options that can be passed into the Rendr App object.
 
 - **dataAdapterConfig** Standard way of configuring the built-in RestAdapter, which is a simple REST pass through.
-- **dataAdapter** _optional_ Allows you to override the default dataAdapter.  The default is a simple REST pass through.  If the `dataAdapter` option is set, the `dataAdapterConfig` will be ignored
+- **dataAdapter** _optional_ Allows you to override the default dataAdapter.  The default is a simple REST pass through.  If the `dataAdapter` option is set, the `dataAdapterConfig` will be ignored.
 - **apiPath** _optional_ Root of the API proxy's virtual path. Anything after this root will be followed by a `-`. Example: `/api/-/path/to/resource`. Allows the proxy to intercept API routes. Can also be a full path to a remote API `http://api.myserver`. The default is set to: `api`
-- **appData** _optional_ Pass any data that needs to be accessible by the client. Accessible from within your Handlebars context `app.attributes.myAttr`, and also within your views and models `this.app.attributes.myAttr`.
+- **appData** _optional_ Pass any data that needs to be accessible by the client.  You can access this data from within your Handlebars context as `app.attributes.myAttr`, and from within your views and models as `this.app.attributes.myAttr`.
 - **defaultEngine** _optional_ Tell the ViewEngine to load different file types. For example: `coffee`.  By default this is set to `js`.
 - **entryPath** _optional_ Root path for the app. Default: `process.cwd() + '/'` (the current working directory)
-- **errorHandler** _optional_ Callback for [Express.js errors](http://expressjs.com/guide.html#error-handling)
-- **notFoundHandler** _optional_ Callback for [Express.js not found errors](http://expressjs.com/guide.html#error-handling)
-- **viewEngine** _optional_ Provides a way to set a custom [Express.js ViewEngine](http://expressjs.com/api.html#app.engine)
+- **errorHandler** _optional_ Callback for [Express.js errors](http://expressjs.com/guide/error-handling.html)
+- **notFoundHandler** _optional_ Callback for [Express.js not found errors](http://expressjs.com/guide/error-handling.html)
+- **viewEngine** _optional_ Set a custom [Express.js ViewEngine](http://expressjs.com/api.html#app.engine)
 - **viewsPath** _optional_ Override where the views are stored. This path is relative to `entryPath`. Default value is: `app/views`
 
 Example configuration:
diff --git a/_app/fetch.md b/_app/fetch.md
@@ -3,7 +3,7 @@ header: fetch
 example: App.fetch(spec)
 ---
 
-Curries the function call for [Fetcher.fetch](/fetcher#fetch).  The spec is an object that is formatted to have the name of the result key, then the fetch information.
+Curries the function call for [Fetcher.fetch](/fetcher#fetch).  The spec is an object containing the name of the result key and the fetch parameters.
 
 Example spec:
 
@@ -25,8 +25,8 @@ var spec = {
     params: { id: 5 }
   }
 
-  // you can also set a collection to be the focus of the view
+  // you can also set a collection to be the focus of the view instead of a model
 }
 ```
 
-App.fetch requests generally take place in the [Controller](/controller), which will make the request for all the required data for a given page.  These `spec`s are also auto generated when you [lazy load](/view#fetchLazy) a view.
+`spec` declarations and `App.fetch` requests usually take place in the [Controller](/controller), which will make the request for all the required data for a given page.  These `spec`s are also auto-generated when you [lazy load](/view#fetchLazy) a view.
diff --git a/_app/start.md b/_app/start.md
@@ -5,4 +5,4 @@ example: App.start()
 
 *Client-side only* Starts the [router](/router), and triggers the `start` event.
 
-Listen to the `start` event to hook into the code when the app starts up.  Activating experiments, loading translations, and starting analytics are pretty common things to do here.
+Listen to the `start` event to add handling code when the app starts up.  Activating experiments, loading translations, and setting up analytics are pretty common things to do here.
diff --git a/_fetcher/fetch.md b/_fetcher/fetch.md
@@ -3,7 +3,7 @@ header: fetch
 example: Fetcher.fetch(fetchSpec, [options], callback)
 ---
 
-`fetchSpec` is an object with the information to fetcher [Models](/model) or [Collections](/collection).
+Fetches [Models](/model) or [Collections](/collection) according to the parameters defined in the `fetchSpec` and populates the corresponding ModelStore and/or CollectionStore.
 
 Example `fetchSpec`:
 
@@ -28,16 +28,16 @@ Example `fetchSpec`:
 }
 ```
 
-This `fetchSpec` will get two models, the User and Character models, and one collection, the StarWarsCharacters collection.
+This `fetchSpec` will get two models (the User and Character models) and one collection (the StarWarsCharacters collection).
 
-Extra options to pass a `fetchSpec`:
+Extra options to pass to a `fetchSpec`:
 
 - *needsFetch* - Allows you to force a fetch request
 - *ensureKeys* - Ensures any stored data has all the required data, if not an API request will be made
 
-The `callback` function will be called with an `error` and `results` from the fetch.  The `error` argument will contain any errors when fetching data.  The `results` argument is an object of results from the API requests.  Each key is defined in the `fetchSpec` where the value is the response from the API.  For an example of what a callback function might look like, check out the [Contoller](/controller) documentation.
+The `callback` function will be called with an `error` and `results` from the fetch.  For an example callback function, check out the [Controller](/controller) documentation.
 
-`options` *optional* Allows you to set caching information.  The defaults for the options differ from client and server.  By default API responses are not written or read from the cache on the server, but both are true on the client.
+`options` *optional* Allows you to set caching information.  The defaults differ between client and server:  by default API responses are not written or read from the cache on the server, but both are true on the client.
 
 Example `options`:
 
@@ -50,4 +50,4 @@ var opts = {
 Fetcher.fetch(fetchSpec, opts, callback);
 ```
 
-The `fetch` function will make an AJAX request if `readFromCache` is false **or** if the data does not exist in the store.  By default on the client, the fetch request will check the corresponding store to see if the data exists, if it does no request is made and it simply returns the value in the store.  If the data isn't found it generates AJAX requests for each item defined in the `fetchSpec`.  **Note**: These AJAX requests are run in parallel.
+The `fetch` function will make an AJAX request if `readFromCache` is false **or** if the data does not exist in the ModelStore or CollectionStore.  If the data isn't found in the relevant store, it makes AJAX requests for each item defined in the `fetchSpec`.  **Note**:  These AJAX requests are run in parallel.
diff --git a/_fetcher/fetchFromApi.md b/_fetcher/fetchFromApi.md
@@ -3,5 +3,5 @@ header: fetchFromApi
 example: Fetcher.fetchFromApi(spec, options, callback)
 ---
 
-Calls fetch for the [model](http://backbonejs.org#Model-fetch) or [collection](http://backbonejs.org#Collection-fetch) with the given options and invokes the callback when the fetch is completed.
+Calls `fetch` for the [model](http://backbonejs.org#Model-fetch) or [collection](http://backbonejs.org#Collection-fetch) with the given options and invokes the callback after the fetch is completed.
 
diff --git a/_fetcher/hydrate.md b/_fetcher/hydrate.md
@@ -3,12 +3,10 @@ header: hydrate
 example: Fetcher.hydrate(summaries, [options], callback)
 ---
 
-The method is used when attaching views to the DOM.  It verifies that the data exists for the summary for each child view, this only retrieves data from the [Model Store](/model-store) or the [Collection Store](/collection-store).
+This method is called when attaching views to the DOM, specifically when [attaching the child views](/view#attachChildViews).  `hydrate` loops through each summary to retrieve the data from the corresponding [Model Store](/model-store) or [Collection Store](/collection-store) for each child view, then it invokes the specified callback.
 
 Arguments:
 
 - `summaries` can be generated by the [Fetcher.summarize](#summarize) function.
 - `options` *optional* can be used to pass an instance of the [app](/app).
-- `callback` callback function, what you want to invoke after the data is retrieved from the store.
-
-This function is used when [attaching the child views](/view#attachChildViews).
+- `callback` this function is invoked after the data is retrieved from the store.
diff --git a/_fetcher/pendingFetches.md b/_fetcher/pendingFetches.md
@@ -3,4 +3,4 @@ header: pendingFetches
 example: Fetcher.pendingFetches
 ---
 
-Is a counter to the number of items currently being fetched.  The [fetch](#fetch) function keeps track of the number of pending fetches.
+A counter for the number of items currently being fetched.  The [fetch](#fetch) function keeps track of the number of pending fetches.
diff --git a/_fetcher/storeResults.md b/_fetcher/storeResults.md
@@ -3,4 +3,4 @@ header: storeResults
 example: Fetcher.storeResults(results)
 ---
 
-Stores each of the items in the `results` object to the corresponding store.
+Saves each item from the `results` object into the corresponding store.
diff --git a/app/index.md b/app/index.md
@@ -5,12 +5,12 @@ title: App - RendrJS
 
 # App
 
-The App is a specialized [Model](/model).  The app is the place where a lot of the choices between client / server happen. Here are some of the major features of the app:
+The App is a specialized [Model](/model).  A lot of the choices between client / server happen in the app. Here are some of its major features:
 
 - Defines the template adapter
 - Initializes the client / server [router](/router)
 - Initializes the [fetcher](/fetcher)
-- Initializes [modelUtils](/model-utils)
+- Initializes modelUtils
 - Initializes the app view, which in turn will initialize all views in use
 - [Starts](#start) the client-side [router](/router)
 - [Bootstraps the data](#bootstrapData) from the server into the client
diff --git a/fetcher/index.md b/fetcher/index.md
@@ -5,7 +5,7 @@ title: "Fetcher - RendrJS"
 
 # Fetcher
 
-The Fetcher is initialized during the [app](/app) initialization.  The class is designed to fetch data from an API on the client or server.  It is attached to the app object and initializes the [Model Store](/model-store) and the [Collection Store](/collection-store).  It also mixes in the [Backbone.Events](http://backbonejs.org#Events) to allow you to trigger the events on client or server the same way you would in Backbone.
+The Fetcher is initialized during the [app](/app) initialization and is attached to the app object.  This class is designed to fetch data from an API on the client or server.  It initializes the [Model Store](/model-store) and [Collection Store](/collection-store), and mixes in the [Backbone.Events](http://backbonejs.org#Events) to allow you to trigger events on client or server the way you would in Backbone.
 
 {% include pageDoc.html name="fetcher" %}
 
diff --git a/model/index.md b/model/index.md
@@ -7,6 +7,6 @@ title: "Model - RendrJS"
 
 Rendr models extend [Backbone Models](http://backbonejs.org#Model).  They are configured to run on the client and server, though some of the functionality works a little different between the two.  You won't normally need to worry about these differences in your project.
 
-The model also mixes-in the **[syncer](/syncer)** functionality for fetching data from an API on the client or the server.
+The model also mixes in the **[syncer](/syncer)** functionality for fetching data from an API on the client or the server.
 
 {% include pageDoc.html name="model" %}

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ header: fetch`
`3`	`3`	`example: App.fetch(spec)`
`4`	`4`	`---`
`5`	`5`
`6`		`-Curries the function call for [Fetcher.fetch](/fetcher#fetch). The spec is an object that is formatted to have the name of the result key, then the fetch information.`
	`6`	`+Curries the function call for [Fetcher.fetch](/fetcher#fetch). The spec is an object containing the name of the result key and the fetch parameters.`
`7`	`7`
`8`	`8`	`Example spec:`
`9`	`9`
`@@ -25,8 +25,8 @@ var spec = {`
`25`	`25`	`params: { id: 5 }`
`26`	`26`	`}`
`27`	`27`
`28`		`- // you can also set a collection to be the focus of the view`
	`28`	`+ // you can also set a collection to be the focus of the view instead of a model`
`29`	`29`	`}`
`30`	`30`	```
`31`	`31`
`32`		-App.fetch requests generally take place in the [Controller](/controller), which will make the request for all the required data for a given page. These `spec`s are also auto generated when you [lazy load](/view#fetchLazy) a view.
	`32`	+`spec` declarations and `App.fetch` requests usually take place in the [Controller](/controller), which will make the request for all the required data for a given page. These `spec`s are also auto-generated when you [lazy load](/view#fetchLazy) a view.
Original file line number	Diff line number	Diff line change
`@@ -5,4 +5,4 @@ example: App.start()`
`5`	`5`
`6`	`6`	Client-side only Starts the [router](/router), and triggers the `start` event.
`7`	`7`
`8`		-Listen to the `start` event to hook into the code when the app starts up. Activating experiments, loading translations, and starting analytics are pretty common things to do here.
	`8`	+Listen to the `start` event to add handling code when the app starts up. Activating experiments, loading translations, and setting up analytics are pretty common things to do here.