From efe33a5e2196efb45596fb64daaec16dfe1da613 Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Thu, 19 Jan 2012 12:39:05 -0800 Subject: docs($http): doc fixes suggested by Gina --- src/service/http.js | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/src/service/http.js b/src/service/http.js index 68f06de7..1176bf77 100644 --- a/src/service/http.js +++ b/src/service/http.js @@ -144,8 +144,8 @@ function $HttpProvider() { * @requires $injector * * @description - * The `$http` service is a core Angular service that is responsible for communication with the - * remote HTTP servers via browser's {@link https://developer.mozilla.org/en/xmlhttprequest + * The `$http` service is a core Angular service that facilitates communication with the remote + * HTTP servers via browser's {@link https://developer.mozilla.org/en/xmlhttprequest * XMLHttpRequest} object or via {@link http://en.wikipedia.org/wiki/JSONP JSONP}. * * For unit testing applications that use `$http` service, see @@ -154,6 +154,10 @@ function $HttpProvider() { * For a higher level of abstraction, please check out the {@link angular.module.ng.$resource * $resource} service. * + * The $http API is based on the {@link angular.module.ng.$q deferred/promise APIs} exposed by + * the $q service. While for simple usage patters this doesn't matter much, for advanced usage, + * it is important to familiarize yourself with these apis and guarantees they provide. + * * * # General usage * The `$http` service is a function which takes a single argument — a configuration object — @@ -173,9 +177,10 @@ function $HttpProvider() { * }); * * - * Since the returned value is a Promise object, you can also use the `then` method to register - * callbacks, and these callbacks will receive a single argument – an object representing the - * response. See the api signature and type info below for more details. + * Since the returned value of calling the $http function is a Promise object, you can also use + * the `then` method to register callbacks, and these callbacks will receive a single argument – + * an object representing the response. See the api signature and type info below for more + * details. * * * # Shortcut methods @@ -199,7 +204,7 @@ function $HttpProvider() { * - {@link angular.module.ng.$http#jsonp $http.jsonp} * * - * # HTTP Headers + * # Setting HTTP Headers * * The $http service will automatically add certain http headers to all requests. These defaults * can be fully configured by accessing the `$httpProvider.defaults.headers` configuration @@ -219,7 +224,7 @@ function $HttpProvider() { * `$httpProvider.defaults.headers.get['My-Header']='value'`. * * - * # Request / Response transformations + * # Transforming Requests and Responses * * Both requests and responses can be transformed using transform functions. By default, Angular * applies these transformations: @@ -234,16 +239,16 @@ function $HttpProvider() { * - if XSRF prefix is detected, strip it (see Security Considerations section below) * - if json response is detected, deserialize it using a JSON parser * - * These transformations can be overridden locally by specifying transform functions as - * `transformRequest` and/or `transformResponse` properties of the config object. To globally - * override the default transforms, override the `$httpProvider.defaults.transformRequest` and + * To override these transformation locally, specify transform functions as `transformRequest` + * and/or `transformResponse` properties of the config object. To globally override the default + * transforms, override the `$httpProvider.defaults.transformRequest` and * `$httpProvider.defaults.transformResponse` properties of the `$httpProvider`. * * * # Caching * - * You can enable caching by setting the configuration property `cache` to `true`. When the - * cache is enabled, `$http` stores the response from the server in local cache. Next time the + * 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. * * Note that even if the response is served from cache, delivery of the data is asynchronous in @@ -256,6 +261,9 @@ function $HttpProvider() { * * # Response interceptors * + * Before you start creating interceptors, be sure to understand the + * {@link angular.module.ng.$q $q and deferred/promise APIs}. + * * For purposes of global error handling, authentication or any kind of synchronous or * asynchronous preprocessing of received responses, it is desirable to be able to intercept * responses for http requests before they are handed over to the application code that @@ -267,9 +275,6 @@ function $HttpProvider() { * injected with dependencies (if specified) and returns the interceptor — a function that * takes a {@link angular.module.ng.$q promise} and returns the original or a new promise. * - * Before you start creating interceptors, be sure to understand the - * {@link angular.module.ng.$q $q and deferred/promise APIs}. - * * 
      *   // register the interceptor as a service
      *   $provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
@@ -300,9 +305,12 @@ function $HttpProvider() {
      *
      * # Security Considerations
      *
-     * When designing web applications your design needs to consider security threats from
-     * {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
-     * JSON Vulnerability} and {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery XSRF}.
+     * When designing web applications, consider security threats from:
+     *
+     * - {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
+     *   JSON Vulnerability}
+     * - {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery XSRF}
+     *
      * Both server and the client must cooperate in order to eliminate these threats. Angular comes
      * pre-configured with strategies that address these issues, but for this to work backend server
      * cooperation is required.
-- 
cgit v1.2.3