diff --git a/packages/common/http/src/client.ts b/packages/common/http/src/client.ts index e6712e116c..b374d471a2 100644 --- a/packages/common/http/src/client.ts +++ b/packages/common/http/src/client.ts @@ -47,14 +47,10 @@ export type HttpObserve = 'body' | 'events' | 'response'; /** * Performs HTTP requests. * - * `HttpClient` is available as an injectable class, with methods to perform HTTP requests. + * This service is available as an injectable class, with methods to perform HTTP requests. * Each request method has multiple signatures, and the return type varies based on * the signature that is called (mainly the values of `observe` and `responseType`). * - * - * @see [HTTP Guide](guide/http) - * - * * @usageNotes * Sample HTTP requests for the [Tour of Heroes](/tutorial/toh-pt0) application. * @@ -75,7 +71,6 @@ export type HttpObserve = 'body' | 'events' | 'response'; * } * ``` * - * * ### PATCH Example * ``` * // PATCH one of the heroes' name @@ -84,7 +79,9 @@ export type HttpObserve = 'body' | 'events' | 'response'; * return this.httpClient.patch(url, {name: heroName}, httpOptions) * .pipe(catchError(this.handleError('patchHero'))); * } -* ``` + * ``` + * + * @see [HTTP Guide](guide/http) * * @publicApi */ diff --git a/packages/common/http/src/headers.ts b/packages/common/http/src/headers.ts index ada6c06a8c..c8ee642e49 100755 --- a/packages/common/http/src/headers.ts +++ b/packages/common/http/src/headers.ts @@ -13,7 +13,8 @@ interface Update { } /** - * `HttpHeaders` class represents the header configuration options for an HTTP request. + * Represents the header configuration options for an HTTP request. + * * Instances should be assumed immutable with lazy parsing. * * @publicApi @@ -35,7 +36,6 @@ export class HttpHeaders { /** * Complete the lazy initialization of this object (needed before reading). */ - // TODO(issue/24571): remove '!'. private lazyInit !: HttpHeaders | Function | null; /** @@ -98,7 +98,7 @@ export class HttpHeaders { } /** - * Returns the first header value that matches a given name. + * Retrieves the first header value that matches a given name. * * @param name The header name to retrieve. * @@ -112,7 +112,7 @@ export class HttpHeaders { } /** - * Returns the names of the headers. + * Retrieves the names of the headers. * * @returns A list of header names. */ @@ -123,7 +123,7 @@ export class HttpHeaders { } /** - * Returns a list of header values for a given header name. + * Retrieves a list of header values for a given header name. * * @param name The header name from which to retrieve the values. * @@ -152,7 +152,7 @@ export class HttpHeaders { * its value is replaced with the given value. * * @param name The header name. - * @param value Provides the value to set or overide for a given name. + * @param value The value to set or overide for a given name. * * @returns A clone of the HTTP header object with the newly set header value. */ diff --git a/packages/common/http/src/interceptor.ts b/packages/common/http/src/interceptor.ts index c7a00d46da..0f71d46eb4 100644 --- a/packages/common/http/src/interceptor.ts +++ b/packages/common/http/src/interceptor.ts @@ -14,7 +14,7 @@ import {HttpRequest} from './request'; import {HttpEvent} from './response'; /** - * Intercepts `HttpRequest` or `HttpResponse` and handles them. + * Intercepts and handles an `HttpRequest` or `HttpResponse`. * * Most interceptors transform the outgoing request before passing it to the * next interceptor in the chain, by calling `next.handle(transformedReq)`. @@ -44,9 +44,11 @@ import {HttpEvent} from './response'; */ export interface HttpInterceptor { /** - * * **req**: The outgoing request to handle - * * **next**: The next interceptor in the chain, or the backend if no interceptors in the chain. - * + * Identifies and handles a given HTTP request. + * @param req The outgoing request object to handle. + * @param next The next interceptor in the chain, or the backend + * if no interceptors remain in the chain. + * @returns An observable of the event stream. */ intercept(req: HttpRequest, next: HttpHandler): Observable>; } @@ -65,8 +67,8 @@ export class HttpInterceptorHandler implements HttpHandler { } /** - * A multi-provider token which represents the array of `HttpInterceptor`s that - * are registered. + * A multi-provider token that represents the array of registered + * `HttpInterceptor` objects. * * @publicApi */ diff --git a/packages/common/http/src/jsonp.ts b/packages/common/http/src/jsonp.ts index 5134f8dcb4..b613434039 100644 --- a/packages/common/http/src/jsonp.ts +++ b/packages/common/http/src/jsonp.ts @@ -39,8 +39,10 @@ export const JSONP_ERR_WRONG_RESPONSE_TYPE = 'JSONP requests must use Json respo export abstract class JsonpCallbackContext { [key: string]: (data: any) => void; } /** - * `HttpBackend` that only processes `HttpRequest` with the JSONP method, + * Processes an `HttpRequest` with the JSONP method, * by performing JSONP style requests. + * @see `HttpHandler` + * @see `HttpXhrBackend` * * @publicApi */ @@ -54,7 +56,10 @@ export class JsonpClientBackend implements HttpBackend { private nextCallback(): string { return `ng_jsonp_callback_${nextRequestId++}`; } /** - * Process a JSONP request and return an event stream of the results. + * Processes a JSONP request and returns an event stream of the results. + * @param req The request object. + * @returns An observable of the response events. + * */ handle(req: HttpRequest): Observable> { // Firstly, check both the method and response type. If either doesn't match @@ -203,15 +208,24 @@ export class JsonpClientBackend implements HttpBackend { } /** - * An `HttpInterceptor` which identifies requests with the method JSONP and + * Identifies requests with the method JSONP and * shifts them to the `JsonpClientBackend`. * + * @see `HttpInterceptor` + * * @publicApi */ @Injectable() export class JsonpInterceptor { constructor(private jsonp: JsonpClientBackend) {} + /** + * Identifies and handles a given JSONP request. + * @param req The outgoing request object to handle. + * @param next The next interceptor in the chain, or the backend + * if no interceptors remain in the chain. + * @returns An observable of the event stream. + */ intercept(req: HttpRequest, next: HttpHandler): Observable> { if (req.method === 'JSONP') { return this.jsonp.handle(req as HttpRequest); diff --git a/packages/common/http/src/params.ts b/packages/common/http/src/params.ts index 4298b6d49e..39c0d31947 100755 --- a/packages/common/http/src/params.ts +++ b/packages/common/http/src/params.ts @@ -22,20 +22,42 @@ export interface HttpParameterCodec { } /** - * A class that uses `encodeURIComponent` and `decodeURIComponent` to - * serialize and parse URL parameter keys and values. If you pass URL query parameters - * without encoding, the query parameters can get misinterpreted at the receiving end. - * Use the `HttpParameterCodec` class to encode and decode the query-string values. + * Provides encoding and decoding of URL parameter and query-string values. + * + * Serializes and parses URL parameter keys and values to encode and decode them. + * If you pass URL query parameters without encoding, + * the query parameters can be misinterpreted at the receiving end. + * * * @publicApi */ export class HttpUrlEncodingCodec implements HttpParameterCodec { + /** + * Encodes a key name for a URL parameter or query-string. + * @param key The key name. + * @returns The encoded key name. + */ encodeKey(key: string): string { return standardEncoding(key); } + /** + * Encodes the value of a URL parameter or query-string. + * @param value The value. + * @returns The encoded value. + */ encodeValue(value: string): string { return standardEncoding(value); } + /** + * Decodes an encoded URL parameter or query-string key. + * @param key The encoded key name. + * @returns The decoded key name. + */ decodeKey(key: string): string { return decodeURIComponent(key); } + /** + * Decodes an encoded URL parameter or query-string value. + * @param value The encoded value. + * @returns The decoded value. + */ decodeValue(value: string) { return decodeURIComponent(value); } } @@ -75,18 +97,21 @@ interface Update { op: 'a'|'d'|'s'; } -/** Options used to construct an `HttpParams` instance. */ +/** Options used to construct an `HttpParams` instance. + * + * @publicApi + */ export interface HttpParamsOptions { /** - * String representation of the HTTP params in URL-query-string format. Mutually exclusive with - * `fromObject`. + * String representation of the HTTP parameters in URL-query-string format. + * Mutually exclusive with `fromObject`. */ fromString?: string; - /** Object map of the HTTP params. Mutually exclusive with `fromString`. */ + /** Object map of the HTTP parameters. Mutually exclusive with `fromString`. */ fromObject?: {[param: string]: string | string[]}; - /** Encoding codec used to parse and serialize the params. */ + /** Encoding codec used to parse and serialize the parameters. */ encoder?: HttpParameterCodec; } @@ -94,7 +119,7 @@ export interface HttpParamsOptions { * An HTTP request/response body that represents serialized parameters, * per the MIME type `application/x-www-form-urlencoded`. * - * This class is immutable - all mutation operations return a new instance. + * This class is immutable; all mutation operations return a new instance. * * @publicApi */ @@ -123,7 +148,10 @@ export class HttpParams { } /** - * Check whether the body has one or more values for the given parameter name. + * Reports whether the body includes one or more values for a given parameter. + * @param param The parameter name. + * @returns True if the parameter has one or more values, + * false if it has no value or is not present. */ has(param: string): boolean { this.init(); @@ -131,7 +159,10 @@ export class HttpParams { } /** - * Get the first value for the given parameter name, or `null` if it's not present. + * Retrieves the first value for a parameter. + * @param param The parameter name. + * @returns The first value of the given parameter, + * or `null` if the parameter is not present. */ get(param: string): string|null { this.init(); @@ -140,7 +171,10 @@ export class HttpParams { } /** - * Get all values for the given parameter name, or `null` if it's not present. + * Retrieves all values for a parameter. + * @param param The parameter name. + * @returns All values in a string array, + * or `null` if the parameter not present. */ getAll(param: string): string[]|null { this.init(); @@ -148,7 +182,8 @@ export class HttpParams { } /** - * Get all the parameter names for this body. + * Retrieves all the parameters for this body. + * @returns The parameter names in a string array. */ keys(): string[] { this.init(); @@ -156,24 +191,32 @@ export class HttpParams { } /** - * Construct a new body with an appended value for the given parameter name. + * Appends a new value to existing values for a parameter. + * @param param The parameter name. + * @param value The new value to add. + * @return A new body with the appended value. */ append(param: string, value: string): HttpParams { return this.clone({param, value, op: 'a'}); } /** - * Construct a new body with a new value for the given parameter name. + * Replaces the value for a parameter. + * @param param The parameter name. + * @param value The new value. + * @return A new body with the new value. */ set(param: string, value: string): HttpParams { return this.clone({param, value, op: 's'}); } /** - * Construct a new body with either the given value for the given parameter - * removed, if a value is given, or all values for the given parameter removed - * if not. + * Removes a given value or all values from a parameter. + * @param param The parameter name. + * @param value The value to remove, if provided. + * @return A new body with the given value removed, or with all values + * removed if no value is specified. */ delete (param: string, value?: string): HttpParams { return this.clone({param, value, op: 'd'}); } /** - * Serialize the body to an encoded string, where key-value pairs (separated by `=`) are + * Serializes the body to an encoded string, where key-value pairs (separated by `=`) are * separated by `&`s. */ toString(): string { diff --git a/packages/common/http/src/xhr.ts b/packages/common/http/src/xhr.ts index 339a7cc739..b1c00e3249 100644 --- a/packages/common/http/src/xhr.ts +++ b/packages/common/http/src/xhr.ts @@ -38,8 +38,7 @@ function getResponseUrl(xhr: any): string|null { export abstract class XhrFactory { abstract build(): XMLHttpRequest; } /** - * A factory for @{link HttpXhrBackend} that uses the `XMLHttpRequest` browser API. - * + * A factory for `HttpXhrBackend` that uses the `XMLHttpRequest` browser API. * */ @Injectable() @@ -59,8 +58,9 @@ interface PartialResponse { } /** - * An `HttpBackend` which uses the XMLHttpRequest API to send - * requests to a backend server. + * Uses `XMLHttpRequest` to send requests to a backend server. + * @see `HttpHandler` + * @see `JsonpClientBackend` * * @publicApi */ @@ -69,7 +69,9 @@ export class HttpXhrBackend implements HttpBackend { constructor(private xhrFactory: XhrFactory) {} /** - * Process a request and return a stream of response events. + * Processes a request and returns a stream of response events. + * @param req The request object. + * @returns An observable of the response events. */ handle(req: HttpRequest): Observable> { // Quick check to give a better error message when a user attempts to use