From c3fadadaa9fa60f7b9d1c0272adebdad2ce2999a Mon Sep 17 00:00:00 2001
From: Vani <psreep@gmail.com>
Date: Wed, 3 Oct 2018 07:44:04 -0700
Subject: [PATCH] docs: update HttpHeader documentation (#26233)

PR Close #26233
---
 packages/common/http/src/headers.ts | 55 +++++++++++++++++++++++++----
 1 file changed, 48 insertions(+), 7 deletions(-)

diff --git a/packages/common/http/src/headers.ts b/packages/common/http/src/headers.ts
index d909cd1f95..ada6c06a8c 100755
--- a/packages/common/http/src/headers.ts
+++ b/packages/common/http/src/headers.ts
@@ -13,7 +13,8 @@ interface Update {
 }
 
 /**
- * Immutable set of Http headers, with lazy parsing.
+ * `HttpHeaders` class represents the header configuration options for an HTTP request.
+ * Instances should be assumed immutable with lazy parsing.
  *
  * @publicApi
  */
@@ -42,6 +43,8 @@ export class HttpHeaders {
    */
   private lazyUpdate: Update[]|null = null;
 
+  /**  Constructs a new HTTP header object with the given values.*/
+
   constructor(headers?: string|{[name: string]: string | string[]}) {
     if (!headers) {
       this.headers = new Map<string, string[]>();
@@ -82,7 +85,11 @@ export class HttpHeaders {
   }
 
   /**
-   * Checks for existence of header by given name.
+   * Checks for existence of a header by a given name.
+   *
+   * @param name The header name to check for existence.
+   *
+   * @returns Whether the header exits.
    */
   has(name: string): boolean {
     this.init();
@@ -91,7 +98,11 @@ export class HttpHeaders {
   }
 
   /**
-   * Returns first header that matches given name.
+   * Returns the first header value that matches a given name.
+   *
+   * @param name The header name to retrieve.
+   *
+   * @returns A string if the header exists, null otherwise
    */
   get(name: string): string|null {
     this.init();
@@ -101,7 +112,9 @@ export class HttpHeaders {
   }
 
   /**
-   * Returns the names of the headers
+   * Returns the names of the headers.
+   *
+   * @returns A list of header names.
    */
   keys(): string[] {
     this.init();
@@ -110,7 +123,11 @@ export class HttpHeaders {
   }
 
   /**
-   * Returns list of header values for a given name.
+   * Returns a list of header values for a given header name.
+   *
+   * @param name The header name from which to retrieve the values.
+   *
+   * @returns A string of values if the header exists, null otherwise.
    */
   getAll(name: string): string[]|null {
     this.init();
@@ -118,14 +135,38 @@ export class HttpHeaders {
     return this.headers.get(name.toLowerCase()) || null;
   }
 
+  /**
+   * Appends a new header value to the existing set of
+   * header values.
+   *
+   * @param name The header name for which to append the values.
+   *
+   * @returns A clone of the HTTP header object with the value appended.
+   */
+
   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.
+   *
+   * @param name The header name.
+   * @param value Provides the value to set or overide for a given name.
+   *
+   * @returns A clone of the HTTP header 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.
+   *
+   * @param name The header name.
+   * @param value The header values to delete for a given name.
+   *
+   * @returns A clone of the HTTP header object.
+   */
   delete (name: string, value?: string|string[]): HttpHeaders {
     return this.clone({name, value, op: 'd'});
   }