From c59fa8b85acd8a4c134a83624ba8e4fe00a71c7a Mon Sep 17 00:00:00 2001
From: SkyZeroZx <73321943+SkyZeroZx@users.noreply.github.com>
Date: Mon, 10 Nov 2025 14:02:18 -0500
Subject: [PATCH] docs: improve discoverability in service worker documentation

(cherry picked from commit dde18c2303cd0cb8a04c01d439746440a9a62026)
---
 packages/service-worker/src/low_level.ts | 2 +-
 packages/service-worker/src/module.ts    | 4 ++++
 packages/service-worker/src/push.ts      | 4 ++++
 packages/service-worker/src/update.ts    | 3 +++
 4 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/service-worker/src/low_level.ts b/packages/service-worker/src/low_level.ts
index ac89788d76d..7a1443c2a79 100644
--- a/packages/service-worker/src/low_level.ts
+++ b/packages/service-worker/src/low_level.ts
@@ -109,7 +109,7 @@ export type VersionEvent =
  * service worker cache has been partially cleaned by the browser, removing some files of a previous
  * app version but not all.
  *
- * @see {@link /ecosystem/service-workers/communications Service Worker Communication Guide}
+ * @see [Handling an unrecoverable state](ecosystem/service-workers/communications#handling-an-unrecoverable-state)
 
  *
  * @publicApi
diff --git a/packages/service-worker/src/module.ts b/packages/service-worker/src/module.ts
index 101fcc4cc13..7cfc7e52dc7 100644
--- a/packages/service-worker/src/module.ts
+++ b/packages/service-worker/src/module.ts
@@ -13,6 +13,10 @@ import {SwPush} from './push';
 import {SwUpdate} from './update';
 
 /**
+ *
+ * @see [Custom service worker script](ecosystem/service-workers/custom-service-worker-scripts)
+ * @see [Service worker configuration](ecosystem/service-workers/getting-started#service-worker-configuration)
+ *
  * @publicApi
  */
 @NgModule({providers: [SwPush, SwUpdate]})
diff --git a/packages/service-worker/src/push.ts b/packages/service-worker/src/push.ts
index 30eba02be53..c5495024f18 100644
--- a/packages/service-worker/src/push.ts
+++ b/packages/service-worker/src/push.ts
@@ -89,6 +89,7 @@ import {ERR_SW_NOT_SUPPORTED, NgswCommChannel, PushEvent} from './low_level';
  * @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)
+ * @see [Push notifications guide](ecosystem/service-workers/push-notifications)
  *
  * @publicApi
  */
@@ -109,6 +110,9 @@ export class SwPush {
    * object that also includes the `title` of the [Notification][Mozilla Notification] object.
    *
    * [Mozilla Notification]: https://developer.mozilla.org/en-US/docs/Web/API/Notification
+   *
+   * @see [Notification click handling](ecosystem/service-workers/push-notifications#notification-click-handling)
+   *
    */
   readonly notificationClicks: Observable<{
     action: string;
diff --git a/packages/service-worker/src/update.ts b/packages/service-worker/src/update.ts
index 461f0ae4e45..283843f8c40 100644
--- a/packages/service-worker/src/update.ts
+++ b/packages/service-worker/src/update.ts
@@ -35,6 +35,9 @@ export class SwUpdate {
    *
    * Emits a `VersionReadyEvent` event whenever a new version has been downloaded and is ready for
    * activation.
+   *
+   * @see [Version updates](ecosystem/service-workers/communications#version-updates)
+   *
    */
   readonly versionUpdates: Observable<VersionEvent>;