service worker: Add documentation about where Mojo interfaces live.

Bug: 795989
Change-Id: Ieb5267a87b43f14a6ae3f3bc29b14402afd2e3ab
Reviewed-on: https://chromium-review.googlesource.com/1166277
Commit-Queue: Matt Falkenhagen <falken@chromium.org>
Reviewed-by: Kinuko Yasuda <kinuko@chromium.org>
Reviewed-by: Makoto Shimazu <shimazu@chromium.org>
Cr-Commit-Position: refs/heads/master@{#584376}

content/common/service_worker/embedded_worker.mojom

@@ -88,6 +88,9 @@ struct EmbeddedWorkerStartTiming {
 // EmbeddedWorkerInstanceHost. It allows control of a renderer-side
 // embedded worker. The browser uses this interface to start, stop, and
 // issue commands to the worker.
+//
+// This interface is the master interface of a dedicated message pipe. It has
+// some interfaces associated with it, like EmbeddedWorkerInstanceHost.
 interface EmbeddedWorkerInstanceClient {
   // Called back as various functions in EmbeddedWorkerInstanceHost, such
   // as OnThreadStarted(), OnStarted().
@@ -102,11 +105,12 @@ interface EmbeddedWorkerInstanceClient {
 };
 
 // EmbeddedWorkerInstanceHost is the browser-side ("Host") of
-// EmbeddedWorkerInstanceClient. It allows control of a browser-side
-// embedded worker instance. The renderer uses this interface to report
-// embedded worker state back to the browser, or request termination of the
-// worker. This interface is associated with the EmbeddedWorkerInstanceClient
-// interface.
+// EmbeddedWorkerInstanceClient. It allows control of a browser-side embedded
+// worker instance. The renderer uses this interface to report embedded worker
+// state back to the browser, or request termination of the worker. This
+// interface is associated with the master interface
+// EmbeddedWorkerInstanceClient, so it lives on the same message pipe as
+// EmbeddedWorkerInstanceClient.
 interface EmbeddedWorkerInstanceHost {
   // S13nServiceWorker:
   // Called when the worker requests to be terminated. The worker will request

content/common/service_worker/service_worker_container.mojom

@@ -19,9 +19,25 @@ enum ControllerServiceWorkerPurpose {
   FETCH_SUB_RESOURCE
 };
 
-// mojom::ServiceWorkerContainerHost is a browser-side interface. The renderer
-// process uses this interface to request the browser process to do operations
-// involving service worker registrations.
+// ServiceWorkerContainerHost is an interface implemented by the browser
+// process. The renderer process uses this interface to request the browser
+// process to do operations involving service worker registrations.
+//
+// This interface is associated with its counterpart ServiceWorkerContainer.
+// The message pipe it's used on depends on the container type.
+// - For service workers:
+//       Associated with EmbeddedWorkerInstanceClient, which is on a dedicated
+//       message pipe.
+// - For shared workers (S13nSW):
+//       Associated with SharedWorkerFactory, which is on a dedicated message
+//       pipe.
+// - For shared workers (non-S13nSW):
+//       Associated with ServiceWorkerDispatcherHost, which is on the
+//       channel-associated interface to the renderer process.
+//       IPC channel.
+// - For documents:
+//       Associated with ServiceWorkerDispatcherHost, which is on the
+//       channel-associated interface to the renderer process.
 interface ServiceWorkerContainerHost {
   // Corresponds to navigator.serviceWorker.register().
   // Registers a service worker from |script_url| with |options|.
@@ -93,9 +109,9 @@ interface ServiceWorkerContainerHost {
   HintToUpdateServiceWorker();
 };
 
-// mojom::ServiceWorkerContainer is a renderer-side interface.
-// The browser process uses this interface to send messages to documents or
-// the service worker.
+// ServiceWorkerContainer is an interface implemented by the renderer process.
+// The browser process uses this interface to send messages to documents or the
+// service worker.
 //
 // Roughly corresponds to the web-exposed ServiceWorkerContainer interface,
 // i.e., navigator.serviceWorker. Actually, the plan is for this interface to be
@@ -105,6 +121,11 @@ interface ServiceWorkerContainerHost {
 // implement navigator.serviceWorker for Worker yet. But eventually anything
 // that can touch these objects should be a ServiceWorkerContainer, so it’s OK
 // to use this name.
+//
+// This interface is associated with its counterpart,
+// ServiceWorkerContainerHost, as they are sent on the same master interface
+// together. See ServiceWorkerContainerHost for documentation about the message
+// pipe they live on.
 interface ServiceWorkerContainer {
   // Corresponds to setting ServiceWorkerContainer#controller.
   // If |controller_info| is invalid (its |object_info| is null), then

content/common/service_worker/service_worker_provider.mojom

@@ -95,13 +95,9 @@ struct ServiceWorkerProviderHostInfo {
 };
 
 // ServiceWorkerWorkerClient represents a service worker client that is a worker
-// (i.e., a shared worker or dedicated worker). We use this interface to let the
-// WebWorkerFetchContextImpl in the worker thread know about the change of
-// controlling service worker by calling OnControllerChanged() from the
-// ServiceWorkerProviderContext in the main thread of the renderer process.
-//
-// TODO(horo): We should implement ServiceWorkerProvider in the worker thread
-// instead of using this interface to support WorkerNavigator.serviceWorker.
+// (i.e., a shared worker or dedicated worker). The main thread of
+// the renderer process uses this interface to tell the worker thread
+// when the controller service worker changes.
 interface ServiceWorkerWorkerClient {
   // Called when the worker is controlled by a new service worker. This is only
   // used to let the worker know that we now have a service worker (while there
@@ -124,9 +120,12 @@ interface ServiceWorkerWorkerClientRegistry {
   CloneWorkerClientRegistry(ServiceWorkerWorkerClientRegistry& host);
 };
 
-// Per-process browser-side interface.
-// The renderer uses this interface to tell the browser when potential service
-// worker clients are created and when service workers are starting up.
+// An interface implemented by the browser process, with one implementation per
+// renderer process. The renderer uses this interface to tell the browser when
+// potential service worker clients are created.
+//
+// This interface is on the channel-associated interface to the renderer
+// process.
 interface ServiceWorkerDispatcherHost {
   // Creates a content::ServiceWorkerProviderHost on the browser
   // process. |provider_info| has Mojo endpoints to connect the container host