honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: clarify http header api doc (#33038) 

PR Close #33038
This commit is contained in:
Judy Bogart 2019-10-08 09:49:33 -07:00 committed by Miško Hevery
parent 72494c4411
commit 8321bd8a74
1 changed files with 22 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
packages/common/http/src/headers.ts
View File

@ -14,8 +14,8 @@ interface Update {
/** /**
* Represents the header configuration options for an HTTP request. * Represents the header configuration options for an HTTP request.
* * Instances are immutable. Modifying methods return a cloned
* Instances should be assumed immutable with lazy parsing. * instance with the change. The original object is never changed.
* *
* @publicApi * @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. * @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 { has(name: string): boolean {
this.init(); 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 { get(name: string): string|null {
this.init(); 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. * @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 * Appends a new value to the existing set of values for a header
* header values. * 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 { append(name: string, value: string|string[]): HttpHeaders {
return this.clone({name, value, op: 'a'}); return this.clone({name, value, op: 'a'});
} }
/** /**
* Sets a header value for a given name. If the header name already exists, * Sets or modifies a value for a given header in a clone of the original instance.
* its value is replaced with the given value. * If the header already exists, its value is replaced with the given value
* in the returned object.
* *
* @param name The header name. * @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 { set(name: string, value: string|string[]): HttpHeaders {
return this.clone({name, value, op: 's'}); 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 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 { delete (name: string, value?: string|string[]): HttpHeaders {
return this.clone({name, value, op: 'd'}); return this.clone({name, value, op: 'd'});