fix(common): document HttpClient, fixing a few other issues

packages/common/http/src/backend.ts

@@ -11,6 +11,15 @@ import {HttpRequest} from './request';
 import {HttpEvent} from './response';
 
 /**
+ * Transforms an `HttpRequest` into a stream of `HttpEvent`s, one of which will likely be a
+ * `HttpResponse`.
+ *
+ * `HttpHandler` is injectable. When injected, the handler instance dispatches requests to the
+ * first interceptor in the chain, which dispatches to the second, etc, eventually reaching the
+ * `HttpBackend`.
+ *
+ * In an `HttpInterceptor`, the `HttpHandler` parameter is the next interceptor in the chain.
+ *
  * @experimental
  */
 export abstract class HttpHandler {
@@ -18,6 +27,13 @@ export abstract class HttpHandler {
 }
 
 /**
+ * A final `HttpHandler` which will dispatch the request via browser HTTP APIs to a backend.
+ *
+ * Interceptors sit between the `HttpClient` interface and the `HttpBackend`.
+ *
+ * When injected, `HttpBackend` dispatches requests directly to the backend, without going
+ * through the interceptor chain.
+ *
  * @experimental
  */
 export abstract class HttpBackend implements HttpHandler {

packages/common/http/testing/src/api.ts

@@ -32,22 +32,86 @@ export abstract class HttpTestingController {
    */
   abstract match(match: string|RequestMatch|((req: HttpRequest<any>) => boolean)): TestRequest[];
 
-  // Expect that exactly one request matches the given parameter.
+  /**
+   * Expect that a single request has been made which matches the given URL, and return its
+   * mock.
+   *
+   * If no such request has been made, or more than one such request has been made, fail with an
+   * error message including the given request description, if any.
+   */
   abstract expectOne(url: string, description?: string): TestRequest;
+
+  /**
+   * Expect that a single request has been made which matches the given parameters, and return
+   * its mock.
+   *
+   * If no such request has been made, or more than one such request has been made, fail with an
+   * error message including the given request description, if any.
+   */
   abstract expectOne(params: RequestMatch, description?: string): TestRequest;
+
+  /**
+   * Expect that a single request has been made which matches the given predicate function, and
+   * return its mock.
+   *
+   * If no such request has been made, or more than one such request has been made, fail with an
+   * error message including the given request description, if any.
+   */
   abstract expectOne(matchFn: ((req: HttpRequest<any>) => boolean), description?: string):
       TestRequest;
+
+  /**
+   * Expect that a single request has been made which matches the given condition, and return
+   * its mock.
+   *
+   * If no such request has been made, or more than one such request has been made, fail with an
+   * error message including the given request description, if any.
+   */
   abstract expectOne(
       match: string|RequestMatch|((req: HttpRequest<any>) => boolean),
       description?: string): TestRequest;
 
-  // Assert that no requests match the given parameter.
+  /**
+   * Expect that no requests have been made which match the given URL.
+   *
+   * If a matching request has been made, fail with an error message including the given request
+   * description, if any.
+   */
   abstract expectNone(url: string, description?: string): void;
+
+  /**
+   * Expect that no requests have been made which match the given parameters.
+   *
+   * If a matching request has been made, fail with an error message including the given request
+   * description, if any.
+   */
   abstract expectNone(params: RequestMatch, description?: string): void;
+
+  /**
+   * Expect that no requests have been made which match the given predicate function.
+   *
+   * If a matching request has been made, fail with an error message including the given request
+   * description, if any.
+   */
   abstract expectNone(matchFn: ((req: HttpRequest<any>) => boolean), description?: string): void;
+
+  /**
+   * Expect that no requests have been made which match the given condition.
+   *
+   * If a matching request has been made, fail with an error message including the given request
+   * description, if any.
+   */
   abstract expectNone(
       match: string|RequestMatch|((req: HttpRequest<any>) => boolean), description?: string): void;
 
-  // Validate that all requests which were issued were flushed.
+  /**
+   * Verify that no unmatched requests are outstanding.
+   *
+   * If any requests are outstanding, fail with an error message indicating which requests were not
+   * handled.
+   *
+   * If `ignoreCancelled` is not set (the default), `verify()` will also fail if cancelled requests
+   * were not explicitly matched.
+   */
   abstract verify(opts?: {ignoreCancelled?: boolean}): void;
 }

packages/common/http/testing/src/backend.ts

@@ -38,10 +38,10 @@ export class HttpClientTestingBackend implements HttpBackend, HttpTestingControl
    * Handle an incoming request by queueing it in the list of open requests.
    */
   handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
-    return new Observable((observer: Observer<HttpEvent<any>>) => {
+    return new Observable((observer: Observer<any>) => {
       const testReq = new TestRequest(req, observer);
       this.open.push(testReq);
-      observer.next({type: HttpEventType.Sent});
+      observer.next({ type: HttpEventType.Sent } as HttpEvent<any>);
       return () => { testReq._cancelled = true; };
     });
   }

packages/common/http/testing/src/request.ts

@@ -30,7 +30,12 @@ export class TestRequest {
 
   constructor(public request: HttpRequest<any>, private observer: Observer<HttpEvent<any>>) {}
 
-
+  /**
+   * Resolve the request by returning a body plus additional HTTP information (such as response
+   * headers) if provided.
+   *
+   * Both successful and unsuccessful responses can be delivered via `flush()`.
+   */
   flush(body: ArrayBuffer|Blob|string|number|Object|(string|number|Object|null)[]|null, opts: {
     headers?: HttpHeaders | {[name: string]: string | string[]},
     status?: number,
@@ -65,6 +70,9 @@ export class TestRequest {
     }
   }
 
+  /**
+   * Resolve the request by returning an `ErrorEvent` (e.g. simulating a network failure).
+   */
   error(error: ErrorEvent, opts: {
     headers?: HttpHeaders | {[name: string]: string | string[]},
     status?: number,
@@ -87,6 +95,10 @@ export class TestRequest {
     }));
   }
 
+  /**
+   * Deliver an arbitrary `HttpEvent` (such as a progress event) on the response stream for this
+   * request.
+   */
   event(event: HttpEvent<any>): void {
     if (this.cancelled) {
       throw new Error(`Cannot send events to a cancelled request.`);