docs: update HttpInterceptor API docs (#26827)

PR Close #26827

packages/common/http/src/interceptor.ts

@@ -14,32 +14,29 @@ import {HttpRequest} from './request';
 import {HttpEvent} from './response';
 
 /**
- * Intercepts `HttpRequest` and handles them.
+ * Intercepts `HttpRequest` or `HttpResponse` and handles them.
  *
- * Most interceptors will transform the outgoing request before passing it to the
+ * Most interceptors transforms the outgoing request before passing it to the
  * next interceptor in the chain, by calling `next.handle(transformedReq)`.
+ * An interceptor may choose to transform the
+ * response event stream as well, by applying additional Rx operators on the stream
+ * returned by `next.handle()`.
  *
- * In rare cases, interceptors may wish to completely handle a request themselves,
+ * More rarely, an interceptor may choose to handle the request itself completely,
- * and not delegate to the remainder of the chain. This behavior is allowed.
+ * and compose a new event stream instead of invoking `next.handle()`. This is an
+ * acceptable behavior, but keep in mind that further interceptors will be skipped entirely.
+ *
+ * It is also rare but valid for an interceptor to return multiple responses on the
+ * event stream for a single request.
  *
  * @publicApi
+ *
  */
 export interface HttpInterceptor {
   /**
-   * Intercept an outgoing `HttpRequest` and optionally transform it or the
+   * * **req**: The outgoing request to handle
-   * response.
+   * * **next**: The next interceptor in the chain
    *
-   * Typically an interceptor will transform the outgoing request before returning
-   * `next.handle(transformedReq)`. An interceptor may choose to transform the
-   * response event stream as well, by applying additional Rx operators on the stream
-   * returned by `next.handle()`.
-   *
-   * More rarely, an interceptor may choose to completely handle the request itself,
-   * and compose a new event stream instead of invoking `next.handle()`. This is
-   * acceptable behavior, but keep in mind further interceptors will be skipped entirely.
-   *
-   * It is also rare but valid for an interceptor to return multiple responses on the
-   * event stream for a single request.
    */
   intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>>;
 }