docs: http api doc edit (#31613)

PR Close #31613

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
  */

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.
    */

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
+   * Identifies and handles a given HTTP request.
-   * * **next**: The next interceptor in the chain, or the backend if no interceptors in the chain.
+   * @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<any>, next: HttpHandler): Observable<HttpEvent<any>>;
 }
@@ -65,8 +67,8 @@ export class HttpInterceptorHandler implements HttpHandler {
 }
 
 /**
- * A multi-provider token which represents the array of `HttpInterceptor`s that
+ * A multi-provider token that represents the array of registered
- * are registered.
+ * `HttpInterceptor` objects.
  *
  * @publicApi
  */

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<never>): Observable<HttpEvent<any>> {
     // 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<any>, next: HttpHandler): Observable<HttpEvent<any>> {
     if (req.method === 'JSONP') {
       return this.jsonp.handle(req as HttpRequest<never>);

packages/common/http/src/params.ts

@@ -22,20 +22,42 @@ export interface HttpParameterCodec {
 }
 
 /**
- * A class that uses `encodeURIComponent` and `decodeURIComponent` to
+ * Provides encoding and decoding of URL parameter and query-string values.
- * 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.
+ * Serializes and parses URL parameter keys and values to encode and decode them.
- * Use the `HttpParameterCodec` class to encode and decode the query-string values.
+ * 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
+   * String representation of the HTTP parameters in URL-query-string format.
-   * `fromObject`.
+   * 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
+   * Removes a given value or all values from a parameter.
-   * removed, if a value is given, or all values for the given parameter removed
+   * @param param The parameter name.
-   * if not.
+   * @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 {

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
+ * Uses `XMLHttpRequest` to send requests to a backend server.
- * 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<any>): Observable<HttpEvent<any>> {
     // Quick check to give a better error message when a user attempts to use