docs($http): improve $http's caching documentation

gentooboontoo · petebacondarwin · commit 717a6705e2f3 · 2013-11-13T20:20:59.000Z
Make the possibility to pass a custom cache instance to $http more obvious. Closes angular#4803
diff --git a/src/ng/http.js b/src/ng/http.js
@@ -324,9 +324,11 @@ function $HttpProvider() {
      *
      * # Caching
      *
-     * To enable caching, set the configuration property `cache` to `true`. When the cache is
-     * enabled, `$http` stores the response from the server in local cache. Next time the
-     * response is served from the cache without sending a request to the server.
+     * To enable caching, set the request configuration `cache` property to `true` (to use default
+     * cache) or to a custom cache object (built with {@link ng.$cacheFactory `$cacheFactory`}).
+     * When the cache is enabled, `$http` stores the response from the server in the specified
+     * cache. The next time the same request is made, the response is served from the cache without
+     * sending a request to the server.
      *
      * Note that even if the response is served from cache, delivery of the data is asynchronous in
      * the same way that real requests are.
@@ -335,9 +337,13 @@ function $HttpProvider() {
      * cache, but the cache is not populated yet, only one request to the server will be made and
      * the remaining requests will be fulfilled using the response from the first request.
      *
-     * A custom default cache built with $cacheFactory can be provided in $http.defaults.cache.
-     * To skip it, set configuration property `cache` to `false`.
+     * You can change the default cache to a new object (built with
+     * {@link ng.$cacheFactory `$cacheFactory`}) by updating the
+     * {@link ng.$http#properties_defaults `$http.defaults.cache`} property. All requests who set
+     * their `cache` property to `true` will now use this cache object.
      *
+     * If you set the default cache to `false` then only requests that specify their own custom
+     * cache object will be cached.
      *
      * # Interceptors
      *

Original file line number	Diff line number	Diff line change
`@@ -324,9 +324,11 @@ function $HttpProvider() {`
`324`	`324`	`*`
`325`	`325`	`* # Caching`
`326`	`326`	`*`
`327`		- * To enable caching, set the configuration property `cache` to `true`. When the cache is
`328`		- * enabled, `$http` stores the response from the server in local cache. Next time the
`329`		`- * response is served from the cache without sending a request to the server.`
	`327`	+ * To enable caching, set the request configuration `cache` property to `true` (to use default
	`328`	+ * cache) or to a custom cache object (built with {@link ng.$cacheFactory `$cacheFactory`}).
	`329`	+ * When the cache is enabled, `$http` stores the response from the server in the specified
	`330`	`+ * cache. The next time the same request is made, the response is served from the cache without`
	`331`	`+ * sending a request to the server.`
`330`	`332`	`*`
`331`	`333`	`* Note that even if the response is served from cache, delivery of the data is asynchronous in`
`332`	`334`	`* the same way that real requests are.`
`@@ -335,9 +337,13 @@ function $HttpProvider() {`
`335`	`337`	`* cache, but the cache is not populated yet, only one request to the server will be made and`
`336`	`338`	`* the remaining requests will be fulfilled using the response from the first request.`
`337`	`339`	`*`
`338`		`- * A custom default cache built with $cacheFactory can be provided in $http.defaults.cache.`
`339`		- * To skip it, set configuration property `cache` to `false`.
	`340`	`+ * You can change the default cache to a new object (built with`
	`341`	+ * {@link ng.$cacheFactory `$cacheFactory`}) by updating the
	`342`	+ * {@link ng.$http#properties_defaults `$http.defaults.cache`} property. All requests who set
	`343`	+ * their `cache` property to `true` will now use this cache object.
`340`	`344`	`*`
	`345`	+ * If you set the default cache to `false` then only requests that specify their own custom
	`346`	`+ * cache object will be cached.`
`341`	`347`	`*`
`342`	`348`	`* # Interceptors`
`343`	`349`	`*`