docs: add push notification usage to api doc (#32139)

PR Close #32139

packages/service-worker/src/push.ts

@@ -14,7 +14,93 @@ import {ERR_SW_NOT_SUPPORTED, NgswCommChannel, PushEvent} from './low_level';
 
 
 /**
- * Subscribe and listen to push notifications from the Service Worker.
+ * Subscribe and listen to
+ * [Web Push Notifications](https://developer.mozilla.org/en-US/docs/Web/API/Push_API/Best_Practices)
+ * through Angular Service Worker.
+ *
+ * @usageNotes
+ *
+ * You can inject a `SwPush` instance into any component or service
+ * as a dependency.
+ *
+ * ```ts
+ * import {SwPush} from '@angular/service-worker';
+ * ...
+ *   constructor(private swPush: SwPush) {}
+ *   ...
+ * ```
+ *
+ * To subscribe, call `SwPush.requestSubscription()`, which asks the user for permission.
+ * The call returns a `Promise` with a new
+ * [`PushSubscription`](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription)
+ * instance.
+ *
+ * ```ts
+ * async subscribeToPush() {
+ *   try {
+ *     const sub = await this.swPush.requestSubscription({
+ *       serverPublicKey: PUBLIC_VAPID_KEY_OF_SERVER,
+ *     });
+ *     // TODO: Send to server.
+ *   } catch (e) {
+ *     console.error('Could not subscribe:', e);
+ *   }
+ * }
+ * ```
+ *
+ * A request is rejected if the user denies permission, or if the browser
+ * blocks or does not support the Push API or ServiceWorkers.
+ * Check `SwPush.isEnabled` to confirm status.
+ *
+ * Invoke Push Notifications by pushing a message with the following payload.
+ *
+ * ```ts
+ * {
+ *   "notification": {
+ *     "actions": NotificationAction[],
+ *     "badge": USVString
+ *     "body": DOMString,
+ *     "data": any,
+ *     "dir": "auto"|"ltr"|"rtl",
+ *     "icon": USVString,
+ *     "image": USVString,
+ *     "lang": DOMString,
+ *     "renotify": boolean,
+ *     "requireInteraction": boolean,
+ *     "silent": boolean,
+ *     "tag": DOMString,
+ *     "timestamp": DOMTimeStamp,
+ *     "title": DOMString,
+ *     "vibrate": number[]
+ *   }
+ * }
+ * ```
+ *
+ * Only `title` is required. See `Notification`
+ * [instance properties](https://developer.mozilla.org/en-US/docs/Web/API/Notification#Instance_properties).
+ *
+ * While the subscription is active, Service Worker listens for
+ * [PushEvent](https://developer.mozilla.org/en-US/docs/Web/API/PushEvent)
+ * occurrences and creates
+ * [Notification](https://developer.mozilla.org/en-US/docs/Web/API/Notification)
+ * instances in response.
+ *
+ * Unsubscribe using `SwPush.unsubscribe()`.
+ *
+ * An application can subscribe to `SwPush.notificationClicks` observable to be notified when a user
+ * clicks on a notification. For example:
+ *
+ * ```ts
+ * swPush.notificationClicks.subscribe(({action, notification}) => {
+ *   // TODO: Do something in response to notification click.
+ * });
+ * ```
+ *
+ * @see [Push Notifications](https://developers.google.com/web/fundamentals/codelabs/push-notifications/)
+ * @see [Angular Push Notifications](https://blog.angular-university.io/angular-push-notifications/)
+ * @see [MDN: Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
+ * @see [MDN: Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
+ * @see [MDN: Web Push API Notifications best practices](https://developer.mozilla.org/en-US/docs/Web/API/Push_API/Best_Practices)
  *
  * @publicApi
  */
@@ -27,10 +113,10 @@ export class SwPush {
 
   /**
    * Emits the payloads of the received push notification messages as well as the action the user
-   * interacted with. If no action was used the action property will be an empty string `''`.
+   * interacted with. If no action was used the `action` property contains an empty string `''`.
    *
-   * Note that the `notification` property is **not** a [Notification][Mozilla Notification] object
-   * but rather a
+   * Note that the `notification` property does **not** contain a
+   * [Notification][Mozilla Notification] object but rather a
    * [NotificationOptions](https://notifications.spec.whatwg.org/#dictdef-notificationoptions)
    * object that also includes the `title` of the [Notification][Mozilla Notification] object.
    *
@@ -78,6 +164,13 @@ export class SwPush {
     this.subscription = merge(workerDrivenSubscriptions, this.subscriptionChanges);
   }
 
+  /**
+   * Subscribes to Web Push Notifications,
+   * after requesting and receiving user permission.
+   *
+   * @param options An object containing the `serverPublicKey` string.
+   * @returns A Promise that resolves to the new subscription object.
+   */
   requestSubscription(options: {serverPublicKey: string}): Promise<PushSubscription> {
     if (!this.sw.isEnabled) {
       return Promise.reject(new Error(ERR_SW_NOT_SUPPORTED));
@@ -98,6 +191,12 @@ export class SwPush {
         });
   }
 
+  /**
+   * Unsubscribes from Service Worker push notifications.
+   *
+   * @returns A Promise that is resolved when the operation succeeds, or is rejected if there is no
+   *          active subscription or the unsubscribe operation fails.
+   */
   unsubscribe(): Promise<void> {
     if (!this.sw.isEnabled) {
       return Promise.reject(new Error(ERR_SW_NOT_SUPPORTED));