message: docs: clarify http header api doc
  PR Close
diff: @@ -14,8 +14,8 @@ interface Update {
  /**
  * Represents the header configuration options for an HTTP request.
  - *
  - * Instances should be assumed immutable with lazy parsing.
  + * Instances are immutable. Modifying methods return a cloned
  + * instance with the change. The original object is never changed.
  *
  * @publicApi
  */
  @@ -85,11 +85,11 @@ export class HttpHeaders {
  }
  /**
  - * Checks for existence of a header by a given name.
  + * Checks for existence of a given header.
  *
  * @param name The header name to check for existence.
  *
  - * @returns Whether the header exits.
  + * @returns True if the header exists, false otherwise.
  */
  has(name: string): boolean {
  this.init();
  @@ -98,11 +98,11 @@ export class HttpHeaders {
  }
  /**
  - * Retrieves the first header value that matches a given name.
  + * Retrieves the first value of a given header.
  *
  - * @param name The header name to retrieve.
  + * @param name The header name.
  *
  - * @returns A string if the header exists, null otherwise
  + * @returns The value string if the header exists, null otherwise
  */
  get(name: string): string|null {
  this.init();
  @@ -123,9 +123,9 @@ export class HttpHeaders {
  }
  /**
  - * Retrieves a list of header values for a given header name.
  + * Retrieves a list of values for a given header.
  *
  - * @param name The header name from which to retrieve the values.
  + * @param name The header name from which to retrieve values.
  *
  * @returns A string of values if the header exists, null otherwise.
  */
  @@ -136,36 +136,38 @@ export class HttpHeaders {
  }
  /**
  - * Appends a new header value to the existing set of
  - * header values.
  + * Appends a new value to the existing set of values for a header
  + * and returns them in a clone of the original instance.
  *
  - * @param name The header name for which to append the values.
  + * @param name The header name for which to append the value or values.
  + * @param value The new value or array of values.
  *
  - * @returns A clone of the HTTP header object with the value appended.
  + * @returns A clone of the HTTP headers object with the value appended to the given header.
  */
  append(name: string, value: string|string[]): HttpHeaders {
  return this.clone({name, value, op: 'a'});
  }
  /**
  - * Sets a header value for a given name. If the header name already exists,
  - * its value is replaced with the given value.
  + * Sets or modifies a value for a given header in a clone of the original instance.
  + * If the header already exists, its value is replaced with the given value
  + * in the returned object.
  *
  * @param name The header name.
  - * @param value The value to set or overide for a given name.
  + * @param value The value or values to set or overide for the given header.
  *
  - * @returns A clone of the HTTP header object with the newly set header value.
  + * @returns A clone of the HTTP headers object with the newly set header value.
  */
  set(name: string, value: string|string[]): HttpHeaders {
  return this.clone({name, value, op: 's'});
  }
  /**
  - * Deletes all header values for a given name.
  + * Deletes values for a given header in a clone of the original instance.
  *
  * @param name The header name.
  - * @param value The header values to delete for a given name.
  + * @param value The value or values to delete for the given header.
  *
  - * @returns A clone of the HTTP header object.
  + * @returns A clone of the HTTP headers object with the given value deleted.
  */
  delete (name: string, value?: string|string[]): HttpHeaders {
  return this.clone({name, value, op: 'd'});
  