docs(http): move examples to `@usageNotes` (#26039)

PR Close #26039

packages/http/src/backends/xhr_backend.ts

@@ -209,6 +209,7 @@ export class CookieXSRFStrategy implements XSRFStrategy {
  * overridden if a different backend implementation should be used,
  * such as in a node backend.
  *
+ * @usageNotes
  * ### Example
  *
  * ```

packages/http/src/base_response_options.ts

@@ -26,6 +26,7 @@ import {ResponseOptionsArgs} from './interfaces';
  * This class may be used in tests to build {@link Response Responses} for
  * mock responses (see {@link MockBackend}).
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -84,6 +85,7 @@ export class ResponseOptions {
    * This may be useful when sharing a base `ResponseOptions` object inside tests,
    * where certain properties may change from test to test.
    *
+   * @usageNotes
    * ### Example
    *
    * ```typescript
@@ -123,6 +125,7 @@ export class ResponseOptions {
  * when configuring an {@link Injector}, in order to override the default options
  * used by {@link Http} to create {@link Response Responses}.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript

packages/http/src/headers.ts

@@ -13,6 +13,7 @@
  * The only known difference between this `Headers` implementation and the spec is the
  * lack of an `entries` method.
  *
+ * @usageNotes
  * ### Example
  *
  * ```

packages/http/src/http.ts

@@ -47,6 +47,7 @@ function mergeOptions(
  * `request` returns an `Observable` which will emit a single {@link Response} when a
  * response is received.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript

packages/http/src/static_response.ts

@@ -21,6 +21,7 @@ import {Headers} from './headers';
  * usually instantiated by end-users, it is the primary object interacted with when it comes time to
  * add data to a view.
  *
+ * @usageNotes
  * ### Example
  *
  * ```

packages/http/src/url_search_params.ts

@@ -25,9 +25,9 @@ function paramParser(rawParams: string = ''): Map<string, string[]> {
  * @deprecated see https://angular.io/guide/http
  **/
 export class QueryEncoder {
-  encodeKey(k: string): string { return standardEncoding(k); }
+  encodeKey(key: string): string { return standardEncoding(key); }
 
-  encodeValue(v: string): string { return standardEncoding(v); }
+  encodeValue(value: string): string { return standardEncoding(value); }
 }
 
 function standardEncoding(v: string): string {

packages/http/testing/src/mock_backend.ts

@@ -16,6 +16,26 @@ import {take} from 'rxjs/operators';
  *
  * Mock Connection to represent a {@link Connection} for tests.
  *
+ * @usageNotes
+ * ### Example of `mockRespond()`
+ *
+ * ```
+ * var connection;
+ * backend.connections.subscribe(c => connection = c);
+ * http.request('data.json').subscribe(res => console.log(res.text()));
+ * connection.mockRespond(new Response(new ResponseOptions({ body: 'fake response' }))); //logs
+ * 'fake response'
+ * ```
+ *
+ * ### Example of `mockError()`
+ *
+ * ```
+ * var connection;
+ * backend.connections.subscribe(c => connection = c);
+ * http.request('data.json').subscribe(res => res, err => console.log(err)));
+ * connection.mockError(new Error('error'));
+ * ```
+ *
  * @deprecated see https://angular.io/guide/http
  */
 export class MockConnection implements Connection {
@@ -48,16 +68,6 @@ export class MockConnection implements Connection {
    * Sends a mock response to the connection. This response is the value that is emitted to the
    * {@link EventEmitter} returned by {@link Http}.
    *
-   * ### Example
-   *
-   * ```
-   * var connection;
-   * backend.connections.subscribe(c => connection = c);
-   * http.request('data.json').subscribe(res => console.log(res.text()));
-   * connection.mockRespond(new Response(new ResponseOptions({ body: 'fake response' }))); //logs
-   * 'fake response'
-   * ```
-   *
    */
   mockRespond(res: Response) {
     if (this.readyState === ReadyState.Done || this.readyState === ReadyState.Cancelled) {
@@ -87,15 +97,6 @@ export class MockConnection implements Connection {
    * returned
    * from {@link Http}.
    *
-   * ### Example
-   *
-   * ```
-   * var connection;
-   * backend.connections.subscribe(c => connection = c);
-   * http.request('data.json').subscribe(res => res, err => console.log(err)));
-   * connection.mockError(new Error('error'));
-   * ```
-   *
    */
   mockError(err?: Error) {
     // Matches ResourceLoader semantics
@@ -110,6 +111,7 @@ export class MockConnection implements Connection {
  * This class can be injected in tests, and should be used to override providers
  * to other backends, such as {@link XHRBackend}.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -187,8 +189,6 @@ export class MockConnection implements Connection {
  * });
  * ```
  *
- * This method only exists in the mock implementation, not in real Backends.
- *
  * @deprecated see https://angular.io/guide/http
  */
 @Injectable()
@@ -198,35 +198,6 @@ export class MockBackend implements ConnectionBackend {
    * of {@link MockConnection} instances that have been created by this backend. Can be subscribed
    * to in order to respond to connections.
    *
-   * ### Example
-   *
-   * ```
-   * import {Injector} from '@angular/core';
-   * import {fakeAsync, tick} from '@angular/core/testing';
-   * import {BaseRequestOptions, ConnectionBackend, Http, RequestOptions} from '@angular/http';
-   * import {Response, ResponseOptions} from '@angular/http';
-   * import {MockBackend, MockConnection} from '@angular/http/testing';
-   *
-   * it('should get a response', fakeAsync(() => {
-   *      let connection:
-   *          MockConnection;  // this will be set when a new connection is emitted from the
-   *                           // backend.
-   *      let text: string;    // this will be set from mock response
-   *      let injector = Injector.create([
-   *        {provide: ConnectionBackend, useClass: MockBackend},
-   *        {provide: RequestOptions, useClass: BaseRequestOptions},
-   *        Http,
-   *      ]);
-   *      let backend = injector.get(ConnectionBackend);
-   *      let http = injector.get(Http);
-   *      backend.connections.subscribe((c: MockConnection) => connection = c);
-   *      http.request('something.json').toPromise().then((res: any) => text = res.text());
-   *      connection.mockRespond(new Response(new ResponseOptions({body: 'Something'})));
-   *      tick();
-   *      expect(text).toBe('Something');
-   *    }));
-   * ```
-   *
    * This property only exists in the mock implementation, not in real Backends.
    */
   connections: any;  //<MockConnection>

tools/public_api_guard/http/http.d.ts

@@ -97,8 +97,8 @@ export declare class JsonpModule {
 
 /** @deprecated */
 export declare class QueryEncoder {
-    encodeKey(k: string): string;
+    encodeKey(key: string): string;
-    encodeValue(v: string): string;
+    encodeValue(value: string): string;
 }
 
 /** @deprecated */