docs(service-worker): improve API docs for SwPush/SwUpdate (#23138)

PR Close #23138

packages/service-worker/src/low_level.ts

@@ -61,19 +61,10 @@ function errorObservable(message: string): Observable<any> {
  * @experimental
  */
 export class NgswCommChannel {
-  /**
-   * @internal
-   */
   readonly worker: Observable<ServiceWorker>;
 
-  /**
-   * @internal
-   */
   readonly registration: Observable<ServiceWorkerRegistration>;
 
-  /**
-   * @internal
-   */
   readonly events: Observable<TypedEvent>;
 
   constructor(private serviceWorker: ServiceWorkerContainer|undefined) {
@@ -100,9 +91,6 @@ export class NgswCommChannel {
     }
   }
 
-  /**
-   * @internal
-   */
   postMessage(action: string, payload: Object): Promise<void> {
     return this.worker
         .pipe(take(1), tap((sw: ServiceWorker) => {
@@ -114,38 +102,23 @@ export class NgswCommChannel {
         .then(() => undefined);
   }
 
-  /**
-   * @internal
-   */
   postMessageWithStatus(type: string, payload: Object, nonce: number): Promise<void> {
     const waitForStatus = this.waitForStatus(nonce);
     const postMessage = this.postMessage(type, payload);
     return Promise.all([waitForStatus, postMessage]).then(() => undefined);
   }
 
-  /**
-   * @internal
-   */
   generateNonce(): number { return Math.round(Math.random() * 10000000); }
 
-  /**
-   * @internal
-   */
   eventsOfType<T extends TypedEvent>(type: T['type']): Observable<T> {
     const filterFn = (event: TypedEvent): event is T => event.type === type;
     return this.events.pipe(filter(filterFn));
   }
 
-  /**
-   * @internal
-   */
   nextEventOfType<T extends TypedEvent>(type: T['type']): Observable<T> {
     return this.eventsOfType(type).pipe(take(1));
   }
 
-  /**
-   * @internal
-   */
   waitForStatus(nonce: number): Promise<void> {
     return this.eventsOfType<StatusEvent>('STATUS')
         .pipe(filter(event => event.nonce === nonce), take(1), map(event => {

packages/service-worker/src/push.ts

@@ -20,13 +20,27 @@ import {ERR_SW_NOT_SUPPORTED, NgswCommChannel, PushEvent} from './low_level';
  */
 @Injectable()
 export class SwPush {
+  /**
+   * Emits the payloads of the received push notification messages.
+   */
   readonly messages: Observable<object>;
+
+  /**
+   * Emits the currently active
+   * [PushSubscription](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription)
+   * associated to the Service Worker registration or `null` if there is no subscription.
+   */
   readonly subscription: Observable<PushSubscription|null>;
 
+  /**
+   * True if the Service Worker is enabled (supported by the browser and enabled via
+   * `ServiceWorkerModule`).
+   */
+  get isEnabled(): boolean { return this.sw.isEnabled; }
+
   // TODO(issue/24571): remove '!'.
   private pushManager !: Observable<PushManager>;
-  private subscriptionChanges: Subject<PushSubscription|null> =
-      new Subject<PushSubscription|null>();
+  private subscriptionChanges = new Subject<PushSubscription|null>();
 
   constructor(private sw: NgswCommChannel) {
     if (!sw.isEnabled) {
@@ -34,22 +48,15 @@ export class SwPush {
       this.subscription = NEVER;
       return;
     }
+
     this.messages = this.sw.eventsOfType<PushEvent>('PUSH').pipe(map(message => message.data));
 
-    this.pushManager = this.sw.registration.pipe(
-        map((registration: ServiceWorkerRegistration) => { return registration.pushManager; }));
+    this.pushManager = this.sw.registration.pipe(map(registration => registration.pushManager));
 
-    const workerDrivenSubscriptions = this.pushManager.pipe(
-        switchMap((pm: PushManager) => pm.getSubscription().then(sub => { return sub; })));
+    const workerDrivenSubscriptions = this.pushManager.pipe(switchMap(pm => pm.getSubscription()));
     this.subscription = merge(workerDrivenSubscriptions, this.subscriptionChanges);
   }
 
-  /**
-   * Returns true if the Service Worker is enabled (supported by the browser and enabled via
-   * ServiceWorkerModule).
-   */
-  get isEnabled(): boolean { return this.sw.isEnabled; }
-
   requestSubscription(options: {serverPublicKey: string}): Promise<PushSubscription> {
     if (!this.sw.isEnabled) {
       return Promise.reject(new Error(ERR_SW_NOT_SUPPORTED));
@@ -62,7 +69,7 @@ export class SwPush {
     }
     pushOptions.applicationServerKey = applicationServerKey;
 
-    return this.pushManager.pipe(switchMap((pm: PushManager) => pm.subscribe(pushOptions)), take(1))
+    return this.pushManager.pipe(switchMap(pm => pm.subscribe(pushOptions)), take(1))
         .toPromise()
         .then(sub => {
           this.subscriptionChanges.next(sub);

packages/service-worker/src/update.ts

@@ -21,9 +21,22 @@ import {ERR_SW_NOT_SUPPORTED, NgswCommChannel, UpdateActivatedEvent, UpdateAvail
  */
 @Injectable()
 export class SwUpdate {
+  /**
+   * Emits an `UpdateAvailableEvent` event whenever a new app version is available.
+   */
   readonly available: Observable<UpdateAvailableEvent>;
+
+  /**
+   * Emits an `UpdateActivatedEvent` event whenever the app has been updated to a new version.
+   */
   readonly activated: Observable<UpdateActivatedEvent>;
 
+  /**
+   * True if the Service Worker is enabled (supported by the browser and enabled via
+   * `ServiceWorkerModule`).
+   */
+  get isEnabled(): boolean { return this.sw.isEnabled; }
+
   constructor(private sw: NgswCommChannel) {
     if (!sw.isEnabled) {
       this.available = NEVER;
@@ -34,12 +47,6 @@ export class SwUpdate {
     this.activated = this.sw.eventsOfType<UpdateActivatedEvent>('UPDATE_ACTIVATED');
   }
 
-  /**
-   * Returns true if the Service Worker is enabled (supported by the browser and enabled via
-   * ServiceWorkerModule).
-   */
-  get isEnabled(): boolean { return this.sw.isEnabled; }
-
   checkForUpdate(): Promise<void> {
     if (!this.sw.isEnabled) {
       return Promise.reject(new Error(ERR_SW_NOT_SUPPORTED));