diff --git a/packages/common/http/src/client.ts b/packages/common/http/src/client.ts
index 258da773a3..e6712e116c 100644
--- a/packages/common/http/src/client.ts
+++ b/packages/common/http/src/client.ts
@@ -18,8 +18,8 @@ import {HttpEvent, HttpResponse} from './response';
 
 
 /**
- * Construct an instance of `HttpRequestOptions<T>` from a source `HttpMethodOptions` and
- * the given `body`. Basically, this clones the object and adds the body.
+ * Constructs an instance of `HttpRequestOptions<T>` from a source `HttpMethodOptions` and
+ * the given `body`. This function clones the object and adds the body.
  */
 function addBody<T>(
     options: {
@@ -45,11 +45,46 @@ function addBody<T>(
 export type HttpObserve = 'body' | 'events' | 'response';
 
 /**
- * Perform HTTP requests.
+ * Performs HTTP requests.
  *
  * `HttpClient` is available as an injectable class, with methods to perform HTTP requests.
- * Each request method has multiple signatures, and the return type varies according to which
- * signature is called (mainly the values of `observe` and `responseType`).
+ * 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.
+ *
+ * ### HTTP Request Example
+ *
+ * ```
+ *  // GET heroes whose name contains search term
+ * searchHeroes(term: string): observable<Hero[]>{
+ *
+ *  const params = new HttpParams({fromString: 'name=term'});
+ *    return this.httpClient.request('GET', this.heroesUrl, {responseType:'json', params});
+ * }
+ * ```
+ * ### JSONP Example
+ * ```
+ * requestJsonp(url, callback = 'callback') {
+ *  return this.httpClient.jsonp(this.heroesURL, callback);
+ * }
+ * ```
+ *
+ *
+ * ### PATCH Example
+ * ```
+ * // PATCH one of the heroes' name
+ * patchHero (id: number, heroName: string): Observable<{}> {
+ * const url = `${this.heroesUrl}/${id}`;   // PATCH api/heroes/42
+ *  return this.httpClient.patch(url, {name: heroName}, httpOptions)
+ *    .pipe(catchError(this.handleError('patchHero')));
+ * }
+* ```
  *
  * @publicApi
  */
@@ -58,14 +93,22 @@ export class HttpClient {
   constructor(private handler: HttpHandler) {}
 
   /**
-   * Send the given `HttpRequest` and return a stream of `HttpEvents`.
+   * Sends an `HTTPRequest` and returns a stream of `HTTPEvents`.
+   *
+   * @return An `Observable` of the response, with the response body as a stream of `HTTPEvents`.
    */
   request<R>(req: HttpRequest<any>): Observable<HttpEvent<R>>;
 
   /**
-   * Construct a request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a request that interprets the body as an `ArrayBuffer` and returns the response in an
+   * `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -77,9 +120,14 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct a request which interprets the body as a `Blob` and returns it.
+   * Constructs a request that interprets the body as a blob and returns
+   * the response as a blob.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type `Blob`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -91,9 +139,14 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a request which interprets the body as text and returns it.
+   * Constructs a request that interprets the body as a text string and
+   * returns a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -105,9 +158,15 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a request that interprets the body as an `ArrayBuffer` and returns the
+   * the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as an array of `HTTPEvents` for the
+   * request.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -118,9 +177,15 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a request which interprets the body as an `Blob` and returns the full event stream.
+   * Constructs a request that interprets the body as a `Blob` and returns
+   * the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of of all `HttpEvents` for the request,
+   * with the response body of type `Blob`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -132,9 +197,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a request which interprets the body as text and returns the full event stream.
+   * Constructs a request which interprets the body as a text string and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HttpEvents` for the reques,
+   * with the response body of type string.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -146,9 +216,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns the full event stream.
+   * Constructs a request which interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the  request.
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   *  with the response body of type `Object`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -161,9 +236,14 @@ export class HttpClient {
   }): Observable<HttpEvent<any>>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns the full event stream.
+   * Constructs a request which interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `R`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body of type `R`.
    */
   request<R>(method: string, url: string, options: {
     body?: any,
@@ -176,9 +256,14 @@ export class HttpClient {
   }): Observable<HttpEvent<R>>;
 
   /**
-   * Construct a request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a request which interprets the body as an `ArrayBuffer`
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body as an `ArrayBuffer`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -190,9 +275,13 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a request which interprets the body as a `Blob` and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of type `Blob`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -204,9 +293,13 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a request which interprets the body as text and returns the full response.
+   * Constructs a request which interprets the body as a text stream and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the HTTP response, with the response body of type string.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -218,9 +311,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns the full response.
+   * Constructs a request which interprets the body as a JSON object and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the full `HTTPResponse`,
+   * with the response body of type `Object`.
    */
   request(method: string, url: string, options: {
     body?: any,
@@ -233,9 +331,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns the full response.
+   * Constructs a request which interprets the body as a JSON object and returns
+   * the full `HTTPResponse` with the response body in the requested type.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `R`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return  An `Observable` of the full `HTTPResponse`, with the response body of type `R`.
    */
   request<R>(method: string, url: string, options: {
     body?: any,
@@ -248,9 +351,14 @@ export class HttpClient {
   }): Observable<HttpResponse<R>>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns it.
+   * Constructs a request which interprets the body as a JSON object and returns the full
+   * `HTTPResponse` as a JSON object.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of type `Object`.
    */
   request(method: string, url: string, options?: {
     body?: any,
@@ -263,9 +371,14 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a request which interprets the body as JSON and returns it.
+   * Constructs a request which interprets the body as a JSON object
+   * with the response body of the requested type.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `R`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of type `R`.
    */
   request<R>(method: string, url: string, options?: {
     body?: any,
@@ -278,10 +391,13 @@ export class HttpClient {
   }): Observable<R>;
 
   /**
-   * Construct a request in a manner where response type and requested `Observable` are not known
-   * statically.
+   * Constructs a request where response type and requested observable are not known statically.
    *
-   * @return an `Observable` of whatever was requested, typed to `any`.
+   * @param method  The HTTP method.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the reuested response, wuth body of type `any`.
    */
   request(method: string, url: string, options?: {
     body?: any,
@@ -294,35 +410,30 @@ export class HttpClient {
   }): Observable<any>;
 
   /**
-   * Constructs an `Observable` for a particular HTTP request that, when subscribed,
+   * Constructs an observable for a generic HTTP request that, when subscribed,
    * fires the request through the chain of registered interceptors and on to the
    * server.
    *
-   * This method can be called in one of two ways. Either an `HttpRequest`
-   * instance can be passed directly as the only parameter, or a method can be
-   * passed as the first parameter, a string URL as the second, and an
-   * options hash as the third.
+   * You can pass an `HttpRequest` directly as the only parameter. In this case,
+   * the call returns an observable of the raw `HttpEvent` stream.
    *
-   * If a `HttpRequest` object is passed directly, an `Observable` of the
-   * raw `HttpEvent` stream will be returned.
+   * Alternatively you can pass an HTTP method as the first parameter,
+   * a URL string as the second, and an options hash containing the request body as the third.
+   * See `addBody()`. In this case, the specified `responseType` and `observe` options determine the
+   * type of returned observable.
+   *   * The `responseType` value determines how a successful response body is parsed.
+   *   * If `responseType` is the default `json`, you can pass a type interface for the resulting
+   * object as a type parameter to the call.
    *
-   * If a request is instead built by providing a URL, the options object
-   * determines the return type of `request()`. In addition to configuring
-   * request parameters such as the outgoing headers and/or the body, the options
-   * hash specifies two key pieces of information about the request: the
-   * `responseType` and what to `observe`.
+   * The `observe` value determines the return type, according to what you are interested in
+   * observing.
+   *   * An `observe` value of events returns an observable of the raw `HttpEvent` stream, including
+   * progress events by default.
+   *   * An `observe` value of response returns an observable of `HttpResponse<T>`,
+   * where the `T` parameter depends on the `responseType` and any optionally provided type
+   * parameter.
+   *   * An `observe` value of body returns an observable of `<T>` with the same `T` body type.
    *
-   * The `responseType` value determines how a successful response body will be
-   * parsed. If `responseType` is the default `json`, a type interface for the
-   * resulting object may be passed as a type parameter to `request()`.
-   *
-   * The `observe` value determines the return type of `request()`, based on what
-   * the consumer is interested in observing. A value of `events` will return an
-   * `Observable<HttpEvent>` representing the raw `HttpEvent` stream,
-   * including progress events by default. A value of `response` will return an
-   * `Observable<HttpResponse<T>>` where the `T` parameter of `HttpResponse`
-   * depends on the `responseType` and any optionally provided type parameter.
-   * A value of `body` will return an `Observable<T>` with the same `T` body type.
    */
   request(first: string|HttpRequest<any>, url?: string, options: {
     body?: any,
@@ -334,14 +445,14 @@ export class HttpClient {
     withCredentials?: boolean,
   } = {}): Observable<any> {
     let req: HttpRequest<any>;
-    // Firstly, check whether the primary argument is an instance of `HttpRequest`.
+    // First, check whether the primary argument is an instance of `HttpRequest`.
     if (first instanceof HttpRequest) {
       // It is. The other arguments must be undefined (per the signatures) and can be
       // ignored.
       req = first as HttpRequest<any>;
     } else {
       // It's a string, so it represents a URL. Construct a request based on it,
-      // and incorporate the remaining arguments (assuming GET unless a method is
+      // and incorporate the remaining arguments (assuming `GET` unless a method is
       // provided.
 
       // Figure out the headers.
@@ -441,9 +552,13 @@ export class HttpClient {
   }
 
   /**
-   * Construct a DELETE request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `DELETE` request that interprets the body as an `ArrayBuffer`
+   *  and returns the response as an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return  An `Observable` of the response body as an `ArrayBuffer`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -455,9 +570,13 @@ export class HttpClient {
 
 
   /**
-   * Construct a DELETE request which interprets the body as a `Blob` and returns it.
+   * Constructs a `DELETE` request that interprets the body as a `Blob` and returns
+   * the response as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response body as a `Blob`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -468,9 +587,13 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a DELETE request which interprets the body as text and returns it.
+   * Constructs a `DELETE` request that interprets the body as a text string and returns
+   * a string.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -481,9 +604,14 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a DELETE request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `DELETE` request that interprets the body as an `ArrayBuffer`
+   *  and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HTTPEvents` for the request,
+   * with response body as an `ArrayBuffer`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -494,9 +622,14 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a DELETE request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `DELETE` request that interprets the body as a `Blob`
+   *  and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all the `HTTPEvents` for the request, with the response body as a
+   * `Blob`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -507,9 +640,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a DELETE request which interprets the body as text and returns the full event stream.
+   * Constructs a `DELETE` request that interprets the body as a text string
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HTTPEvents` for the request, with the response
+   *  body of type string.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -520,9 +658,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `DELETE` request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HTTPEvents` for the request, with response body of
+   * type `Object`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -534,9 +677,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `DELETE`request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all the `HTTPEvents` for the request, with a response
+   * body in the requested type.
    */
   delete<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -548,9 +696,13 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a DELETE request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a `DELETE` request that interprets the body as an `ArrayBuffer` and returns
+   *  the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the full `HTTPResponse`, with the response body as an `ArrayBuffer`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -561,9 +713,13 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a DELETE request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `DELETE` request that interprets the body as a `Blob` and returns the full
+   * `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of type `Blob`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -574,9 +730,13 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a DELETE request which interprets the body as text and returns the full response.
+   * Constructs a `DELETE` request that interprets the body as a text stream and
+   *  returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the full `HTTPResponse`, with the response body of type string.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -587,9 +747,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns the full response.
+   * Constructs a `DELETE` request the interprets the body as a JSON object and returns
+   * the full `HTTPResponse`.
+   *
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of type `Object`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -601,9 +766,13 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns the full response.
+   * Constructs a `DELETE` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with the response body of the requested type.
    */
   delete<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -615,9 +784,13 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns it.
+   * Constructs a `DELETE` request that interprets the body as a JSON object and
+   * returns the response body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type `Object`.
    */
   delete (url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -629,9 +802,13 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a DELETE request which interprets the body as JSON and returns it.
+   * Constructs a DELETE request that interprets the body as a JSON object and returns
+   * the response in a given type.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with response body in the requested type.
    */
   delete<T>(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -643,9 +820,13 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * DELETE request to be executed on the server. See the individual overloads for
-   * details of `delete()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `DELETE` request to execute on the server. See the individual overloads for
+   * details on the return type.
+   *
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
    */
   delete (url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -660,9 +841,13 @@ export class HttpClient {
 
 
   /**
-   * Construct a GET request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `GET` request that interprets the body as an `ArrayBuffer` and returns the response in
+   *  an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -673,9 +858,13 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct a GET request which interprets the body as a `Blob` and returns it.
+   * Constructs a `GET` request that interprets the body as a `Blob`
+   * and returns the response as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -686,9 +875,13 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a GET request which interprets the body as text and returns it.
+   * Constructs a `GET` request that interprets the body as a text string
+   * and returns the response as a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -699,9 +892,14 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a GET request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `GET` request that interprets the body as an `ArrayBuffer` and returns
+   *  the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HttpEvents` for the request, with the response
+   * body as an `ArrayBuffer`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -712,9 +910,13 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a GET request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `GET` request that interprets the body as a `Blob` and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -725,9 +927,13 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a GET request which interprets the body as text and returns the full event stream.
+   * Constructs a `GET` request that interprets the body as a text string and returns
+   * the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -738,9 +944,13 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `GET` request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type `Object`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -752,9 +962,12 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `GET` request that interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with a response body in the requested type.
    */
   get<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -766,9 +979,14 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a GET request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a `GET` request that interprets the body as an `ArrayBuffer` and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -779,9 +997,14 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a GET request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `GET` request that interprets the body as a `Blob` and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   *  with the response body as a `Blob`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -792,9 +1015,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a GET request which interprets the body as text and returns the full response.
+   * Constructs a `GET` request that interprets the body as a text stream and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body of type string.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -805,9 +1033,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns the full response.
+   * Constructs a `GET` request that interprets the body as a JSON object and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the full `HttpResponse`,
+   * with the response body of type `Object`.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -819,9 +1052,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns the full response.
+   * Constructs a `GET` request that interprets the body as a JSON object and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the full `HTTPResponse` for the request,
+   * with a response body in the requested type.
    */
   get<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -833,9 +1071,14 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns it.
+   * Constructs a `GET` request that interprets the body as a JSON object and
+   * returns the response body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   *
+   * @return An `Observable` of the response body as a JSON object.
    */
   get(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -847,9 +1090,13 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a GET request which interprets the body as JSON and returns it.
+   * Constructs a `GET` request that interprets the body as a JSON object and returns
+   * the response body in a given type.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with a response body in the requested type.
    */
   get<T>(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -861,9 +1108,9 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * GET request to be executed on the server. See the individual overloads for
-   * details of `get()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `GET` request to execute on the server. See the individual overloads for
+   * details on the return type.
    */
   get(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -878,9 +1125,13 @@ export class HttpClient {
 
 
   /**
-   * Construct a HEAD request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `HEAD` request that interprets the body as an `ArrayBuffer` and
+   * returns the response as an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -888,13 +1139,18 @@ export class HttpClient {
     params?: HttpParams|{[param: string]: string | string[]},
     reportProgress?: boolean,
     responseType: 'arraybuffer', withCredentials?: boolean,
-
-    /**
-   * Construct a HEAD request which interprets the body as a `Blob` and returns it.
-   *
-   * @return an `Observable` of the body as a `Blob`.
-   */
   }): Observable<ArrayBuffer>;
+
+  /**
+   * Constructs a `HEAD` request that interprets the body as a `Blob` and returns
+   * the response as a `Blob`.
+   *
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return  An `Observable` of the response, with the response body as a `Blob`.
+   */
+
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
     observe?: 'body',
@@ -904,9 +1160,13 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a HEAD request which interprets the body as text and returns it.
+   * Constructs a `HEAD` request that interprets the body as a text string and returns the response
+   * as a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -917,9 +1177,14 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a HEAD request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `HEAD` request that interprets the body as an  `ArrayBuffer`
+   *  and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of tall `HttpEvents` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -930,9 +1195,14 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a HEAD request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `HEAD` request that interprets the body as a `Blob` and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body as a `Blob`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -943,9 +1213,13 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a HEAD request which interprets the body as text and returns the full event stream.
+   * Constructs a `HEAD` request that interprets the body as a text string
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all HttpEvents for the request, with the response body of type string.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -956,9 +1230,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `HEAD` request that interprets the body as a JSON object
+   * and returns the full HTTP event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of all `HTTPEvents` for the request, with a response body of
+   * type `Object`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -970,9 +1249,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `HEAD` request that interprets the body as a JSON object and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @return An `Observable` of all the `HTTPEvents` for the request
+   * , with a response body in the requested type.
+   *
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
    */
   head<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -984,9 +1268,14 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a HEAD request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a `HEAD` request that interprets the body as an `ArrayBuffer`
+   *  and returns the full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -997,9 +1286,14 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a HEAD request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `HEAD` request that interprets the body as a `Blob` and returns
+   * the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body as a blob.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1010,9 +1304,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a HEAD request which interprets the body as text and returns the full response.
+   * Constructs a `HEAD` request that interprets the body as text stream
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body of type string.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1023,9 +1322,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns the full response.
+   * Constructs a `HEAD` request that interprets the body as a JSON object and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body of type `Object`.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1037,9 +1341,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns the full response.
+   * Constructs a `HEAD` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with a responmse body of the requested type.
    */
   head<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1051,9 +1360,13 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns it.
+   * Constructs a `HEAD` request that interprets the body as a JSON object and
+   * returns the response body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the response, with the response body as a JSON object.
    */
   head(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1065,9 +1378,14 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a HEAD request which interprets the body as JSON and returns it.
+   * Constructs a `HEAD` request that interprets the body as a JSON object and returns
+   * the response in a given type.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url     The endpoint URL.
+   * @param options The HTTP options to send with the request.
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with a response body of the given type.
    */
   head<T>(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1079,9 +1397,11 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * HEAD request to be executed on the server. See the individual overloads for
-   * details of `head()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `HEAD` request to execute on the server. The `HEAD` method returns
+   * meta information about the resource without transferring the
+   * resource itself. See the individual overloads for
+   * details on the return type.
    */
   head(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1095,26 +1415,46 @@ export class HttpClient {
   }
 
   /**
-   * Construct a JSONP request for the given URL and name of the callback parameter.
+   * Constructs a `JSONP` request for the given URL and name of the callback parameter.
    *
-   * @return an `Observable` of the response object as an `Object`
+   * @param url The resource URL.
+   * @param callbackParam The callback function name.
+   *
+   * @return An `Observable` of the response object, with response body as an object.
    */
   jsonp(url: string, callbackParam: string): Observable<Object>;
 
   /**
-   * Construct a JSONP request for the given URL and name of the callback parameter.
+   * Constructs a `JSONP` request for the given URL and name of the callback parameter.
    *
-   * @return an `Observable` of the response object as type `T`.
+   * @param url The resource URL.
+   * @param callbackParam The callback function name.
+   *
+   * You must install a suitable interceptor, such as one provided by `HttpClientJsonpModule`.
+   * If no such interceptor is reached,
+   * then the `JSONP` request can be rejected by the configured backend.
+   *
+   * @return An `Observable` of the response object, with response body in the requested type.
    */
   jsonp<T>(url: string, callbackParam: string): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause a request
-   * with the special method `JSONP` to be dispatched via the interceptor pipeline.
+   * Constructs an `Observable` that, when subscribed, causes a request with the special method
+   * `JSONP` to be dispatched via the interceptor pipeline.
+   * The [JSONP pattern](https://en.wikipedia.org/wiki/JSONP) works around limitations of certain
+   * API endpoints that don't support newer,
+   * and preferable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) protocol.
+   * JSONP treats the endpoint API as a JavaScript file and tricks the browser to process the
+   * requests even if the API endpoint is not located on the same domain (origin) as the client-side
+   * application making the request.
+   * The endpoint API must support JSONP callback for JSONP requests to work.
+   * The resource API returns the JSON response wrapped in a callback function.
+   * You can pass the callback function name as one of the query parameters.
+   * Note that JSONP requests can only be used with `GET` requests.
+   *
+   * @param url The resource URL.
+   * @param callbackParam The callback function name.
    *
-   * A suitable interceptor must be installed (e.g. via the `HttpClientJsonpModule`).
-   * If no such interceptor is reached, then the `JSONP` request will likely be
-   * rejected by the configured backend.
    */
   jsonp<T>(url: string, callbackParam: string): Observable<T> {
     return this.request<any>('JSONP', url, {
@@ -1125,9 +1465,13 @@ export class HttpClient {
   }
 
   /**
-   * Make an OPTIONS request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs an `OPTIONS` request that interprets the body as an
+   * `ArrayBuffer` and returns the response as an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1138,9 +1482,13 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as a `Blob` and returns it.
+   * Constructs an `OPTIONS` request that interprets the body as a `Blob` and returns
+   * the response as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1151,9 +1499,13 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as text and returns it.
+   * Constructs an `OPTIONS` request that interprets the body as a text string and
+   * returns a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body of type string.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1164,9 +1516,14 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs an `OPTIONS` request that interprets the body as an `ArrayBuffer`
+   *  and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return  An `Observable` of all `HttpEvents` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1177,9 +1534,14 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs an `OPTIONS` request that interprets the body as a `Blob` and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body as a `Blob`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1190,9 +1552,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as text and returns the full event stream.
+   * Constructs an `OPTIONS` request that interprets the body as a text string
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPEvents` for the request,
+   * with the response body of type string.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1203,9 +1570,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns the full event stream.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HttpEvents` for the request with the response
+   * body of type `Object`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1217,9 +1589,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns the full event stream.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HttpEvents` for the request,
+   * with a response body in the requested type.
    */
   options<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1231,9 +1608,14 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs an `OPTIONS` request that interprets the body as an `ArrayBuffer`
+   *  and returns the full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1244,9 +1626,14 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as a `Blob` and returns the full response.
+   * Constructs an `OPTIONS` request that interprets the body as a `Blob`
+   *  and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   *  with the response body as a `Blob`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1257,9 +1644,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as text and returns the full response.
+   * Constructs an `OPTIONS` request that interprets the body as text stream
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   *  with the response body of type string.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1270,9 +1662,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns the full response.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   * with the response body of type `Object`.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1284,9 +1681,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns the full response.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object and
+   * returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   * with a response body in the requested type.
    */
   options<T>(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1298,9 +1700,13 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns it.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object and returns the response
+   * body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as a JSON object.
    */
   options(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1312,9 +1718,13 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct an OPTIONS request which interprets the body as JSON and returns it.
+   * Constructs an `OPTIONS` request that interprets the body as a JSON object and returns the response
+   * in a given type.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url The endpoint URL.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HTTPResponse`, with a response body of the given type.
    */
   options<T>(url: string, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1326,9 +1736,11 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * OPTIONS request to be executed on the server. See the individual overloads for
-   * details of `options()`'s return type based on the provided options.
+   * Constructs an `Observable` that, when subscribed, causes the configured
+   * `OPTIONS` request to execute on the server. This method allows the client
+   * to determine the supported HTTP methods and other capabilites of an endpoint,
+   * without implying a resource action. See the individual overloads for
+   * details on the return type.
    */
   options(url: string, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1342,9 +1754,14 @@ export class HttpClient {
   }
 
   /**
-   * Construct a PATCH request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `PATCH` request that interprets the body as an `ArrayBuffer` and returns
+   * the response as an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1355,9 +1772,14 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct a PATCH request which interprets the body as a `Blob` and returns it.
+   * Constructs a `PATCH` request that interprets the body as a `Blob` and returns the response
+   * as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1368,9 +1790,14 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a PATCH request which interprets the body as text and returns it.
+   * Constructs a `PATCH` request that interprets the body as as a text string and
+   * returns the response as a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with a response body of type string.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1381,10 +1808,17 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a PATCH request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `PATCH` request that interprets the body as an `ArrayBuffer` and
+   *  returns the the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPevents` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
+
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
     observe: 'events',
@@ -1394,9 +1828,15 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a PATCH request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `PATCH` request that interprets the body as a `Blob`
+   *  and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPevents` for the request, with the
+   * response body as `Blob`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1407,9 +1847,15 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a PATCH request which interprets the body as text and returns the full event stream.
+   * Constructs a `PATCH` request that interprets the body as a text string and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPevents`for the request, with a
+   * response body of type string.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1420,9 +1866,15 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `PATCH` request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPevents` for the request,
+   * with a response body of type `Object`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1434,9 +1886,15 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `PATCH` request that interprets the body as a JSON object
+   * and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of all the `HTTPevents` for the request,
+   *  with a response body in the requested type.
    */
   patch<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1448,9 +1906,15 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a PATCH request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a `PATCH` request that interprets the body as an `ArrayBuffer`
+   *  and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return  An `Observable` of the `HttpResponse` for the request,
+   *  with the response body as an `ArrayBuffer`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1461,9 +1925,15 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a PATCH request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `PATCH` request that interprets the body as a `Blob` and returns the full
+   * `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return  An `Observable` of the `HttpResponse` for the request,
+   * with the response body as a `Blob`.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1474,9 +1944,15 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a PATCH request which interprets the body as text and returns the full response.
+   * Constructs a `PATCH` request that interprets the body as a text stream and returns the
+   * full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return  An `Observable` of the `HttpResponse` for the request,
+   * with a response body of type string.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1487,9 +1963,15 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns the full response.
+   * Constructs a `PATCH` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   * with a response body in the requested type.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1501,9 +1983,15 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns the full response.
+   * Constructs a `PATCH` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the `HttpResponse` for the request,
+   * with a response body in the given type.
    */
   patch<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1515,9 +2003,14 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns it.
+   * Constructs a `PATCH` request that interprets the body as a JSON object and
+   * returns the response body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as a JSON object.
    */
   patch(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1529,9 +2022,15 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a PATCH request which interprets the body as JSON and returns it.
+   * Constructs a `PATCH` request that interprets the body as a JSON object
+   * and returns the response in a given type.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to edit.
+   * @param options HTTP options.
+   *
+   * @return  An `Observable` of the `HttpResponse` for the request,
+   * with a response body in the given type.
    */
   patch<T>(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1543,9 +2042,9 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * PATCH request to be executed on the server. See the individual overloads for
-   * details of `patch()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `PATCH` request to execute on the server. See the individual overloads for
+   * details on the return type.
    */
   patch(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1559,9 +2058,14 @@ export class HttpClient {
   }
 
   /**
-   * Construct a POST request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `POST` request that interprets the body as an as an `ArrayBuffer` and returns
+   * an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options.
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1572,9 +2076,14 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct a POST request which interprets the body as a `Blob` and returns it.
+   * Constructs a `POST` request that interprets the body as a `Blob` and returns the
+   * response as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1585,9 +2094,14 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a POST request which interprets the body as text and returns it.
+   * Constructs a `POST` request that interprets the body as a text string and
+   * returns the response as a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with a response body of type string.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1598,9 +2112,15 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a POST request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `POST` request that interprets the body as an `ArrayBuffer` and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1611,9 +2131,14 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a POST request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `POST` request that interprets the body as a `Blob`
+   * and returns the response in an observable of the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request, with the response body as `Blob`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1624,9 +2149,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a POST request which interprets the body as text and returns the full event stream.
+   * Constructs a `POST` request that interprets the body as a text string and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return  An `Observable` of all `HttpEvents` for the request,
+   * with a response body of type string.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1637,9 +2167,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns the full event stream.
+   * Constructs a POST request that interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return  An `Observable` of all `HttpEvents` for the request,
+   * with a response body of type `Object`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1651,9 +2186,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns the full event stream.
+   * Constructs a POST request that interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with a response body in the requested type.
    */
   post<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1665,9 +2205,14 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a POST request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a POST request that interprets the body as an `ArrayBuffer`
+   *  and returns the full `HTTPresponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return  An `Observable` of the `HTTPResponse` for the request, with the response body as an `ArrayBuffer`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1678,9 +2223,15 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a POST request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `POST` request that interprets the body as a `Blob` and returns the full
+   * `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body as a `Blob`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1691,9 +2242,15 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a POST request which interprets the body as text and returns the full response.
+   * Constructs a `POST` request that interprets the body as a text stream and returns
+   * the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return  An `Observable` of the `HTTPResponse` for the request,
+   * with a response body of type string.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1704,9 +2261,15 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns the full response.
+   * Constructs a `POST` request that interprets the body as a JSON object
+   * and returns the full `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with a response body of type
+   * `Object`.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1718,9 +2281,15 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns the full response.
+   * Constructs a `POST` request that interprets the body as a JSON object and returns the full
+   * `HTTPResponse`.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   *
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with a response body in the requested type.
    */
   post<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1732,9 +2301,14 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns it.
+   * Constructs a `POST` request that interprets the body as a
+   * JSON object and returns the response body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with the response body as a JSON object.
    */
   post(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1746,9 +2320,14 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a POST request which interprets the body as JSON and returns it.
+   * Constructs a `POST` request that interprets the body as a JSON object
+   * and returns an observable of the response.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url The endpoint URL.
+   * @param body The content to replace with.
+   * @param options HTTP options
+   *
+   * @return  An `Observable` of the `HTTPResponse` for the request, with a response body in the requested type.
    */
   post<T>(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1760,9 +2339,10 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * POST request to be executed on the server. See the individual overloads for
-   * details of `post()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `POST` request to execute on the server. The server responds with the location of
+   * the replaced resource. See the individual overloads for
+   * details on the return type.
    */
   post(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1776,9 +2356,14 @@ export class HttpClient {
   }
 
   /**
-   * Construct a PUT request which interprets the body as an `ArrayBuffer` and returns it.
+   * Constructs a `PUT` request that interprets the body as an `ArrayBuffer` and returns the
+   * response as an `ArrayBuffer`.
    *
-   * @return an `Observable` of the body as an `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with the response body as an `ArrayBuffer`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1789,9 +2374,14 @@ export class HttpClient {
   }): Observable<ArrayBuffer>;
 
   /**
-   * Construct a PUT request which interprets the body as a `Blob` and returns it.
+   * Constructs a `PUT` request that interprets the body as a `Blob` and returns
+   * the response as a `Blob`.
    *
-   * @return an `Observable` of the body as a `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with the response body as a `Blob`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1802,9 +2392,14 @@ export class HttpClient {
   }): Observable<Blob>;
 
   /**
-   * Construct a PUT request which interprets the body as text and returns it.
+   * Constructs a `PUT` request that interprets the body as a text string and
+   * returns the response as a string value.
    *
-   * @return an `Observable` of the body as a `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with a response body of type string.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1815,9 +2410,15 @@ export class HttpClient {
   }): Observable<string>;
 
   /**
-   * Construct a PUT request which interprets the body as an `ArrayBuffer` and returns the full event stream.
+   * Constructs a `PUT` request that interprets the body as an `ArrayBuffer` and
+   * returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body as an `ArrayBuffer`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1828,9 +2429,14 @@ export class HttpClient {
   }): Observable<HttpEvent<ArrayBuffer>>;
 
   /**
-   * Construct a PUT request which interprets the body as a `Blob` and returns the full event stream.
+   * Constructs a `PUT` request that interprets the body as a `Blob` and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with the response body as a `Blob`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1841,9 +2447,14 @@ export class HttpClient {
   }): Observable<HttpEvent<Blob>>;
 
   /**
-   * Construct a PUT request which interprets the body as text and returns the full event stream.
+   * Constructs a `PUT` request that interprets the body as a text string and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all HttpEvents for the request, with a response body
+   * of type string.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1854,9 +2465,14 @@ export class HttpClient {
   }): Observable<HttpEvent<string>>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `PUT` request that interprets the body as a JSON object and returns the full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request, with a response body of
+   * type `Object`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1868,9 +2484,15 @@ export class HttpClient {
   }): Observable<HttpEvent<Object>>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns the full event stream.
+   * Constructs a `PUT` request that interprets the body as a JSON object and returns the
+   * full event stream.
    *
-   * @return an `Observable` of all `HttpEvent`s for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of all `HttpEvents` for the request,
+   * with a response body in the requested type.
    */
   put<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1878,9 +2500,14 @@ export class HttpClient {
   }): Observable<HttpEvent<T>>;
 
   /**
-   * Construct a PUT request which interprets the body as an `ArrayBuffer` and returns the full response.
+   * Constructs a `PUT` request that interprets the body as an
+   * `ArrayBuffer` and returns an observable of the full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `ArrayBuffer`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with the response body as an `ArrayBuffer`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1891,9 +2518,15 @@ export class HttpClient {
   }): Observable<HttpResponse<ArrayBuffer>>;
 
   /**
-   * Construct a PUT request which interprets the body as a `Blob` and returns the full response.
+   * Constructs a `PUT` request that interprets the body as a `Blob` and returns the
+   * full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Blob`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with the response body as a `Blob`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1904,9 +2537,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Blob>>;
 
   /**
-   * Construct a PUT request which interprets the body as text and returns the full response.
+   * Constructs a `PUT` request that interprets the body as a text stream and returns the
+   * full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `string`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with a response body of type string.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1917,9 +2555,14 @@ export class HttpClient {
   }): Observable<HttpResponse<string>>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns the full response.
+   * Constructs a `PUT` request that interprets the body as a JSON object and returns the full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with a response body
+   * of type 'Object`.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1931,9 +2574,14 @@ export class HttpClient {
   }): Observable<HttpResponse<Object>>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns the full response.
+   * Constructs a `PUT` request that interprets the body as a JSON object and returns the full HTTP response.
    *
-   * @return an `Observable` of the `HttpResponse` for the request, with a body type of `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request,
+   * with a response body in the requested type.
    */
   put<T>(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1945,9 +2593,14 @@ export class HttpClient {
   }): Observable<HttpResponse<T>>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns it.
+   * Constructs a `PUT` request that interprets the body as a JSON object and returns the response
+   * body as a JSON object.
    *
-   * @return an `Observable` of the body as an `Object`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the response, with the response body as a JSON object.
    */
   put(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1959,9 +2612,14 @@ export class HttpClient {
   }): Observable<Object>;
 
   /**
-   * Construct a PUT request which interprets the body as JSON and returns it.
+   * Constructs a `PUT` request that interprets the body as a JSON object
+   * and returns an observable of the response.
    *
-   * @return an `Observable` of the body as type `T`.
+   * @param url The endpoint URL.
+   * @param body The resources to add/update.
+   * @param options HTTP options
+   *
+   * @return An `Observable` of the `HTTPResponse` for the request, with a response body in the requested type.
    */
   put<T>(url: string, body: any|null, options?: {
     headers?: HttpHeaders | {[header: string]: string | string[]},
@@ -1973,9 +2631,10 @@ export class HttpClient {
   }): Observable<T>;
 
   /**
-   * Constructs an `Observable` which, when subscribed, will cause the configured
-   * PUT request to be executed on the server. See the individual overloads for
-   * details of `put()`'s return type based on the provided options.
+   * Constructs an observable that, when subscribed, causes the configured
+   * `PUT` request to execute on the server. The `PUT` method replaces an existing resource
+   * with a new set of values.
+   * See the individual overloads for details on the return type.
    */
   put(url: string, body: any|null, options: {
     headers?: HttpHeaders | {[header: string]: string | string[]},