Document HostedMode, canDock, and remoteBase

Change-Id: Ib56ab92284144e376b51e1d7aaf64ff2bdcbfa82
Bug: none
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6765826
Auto-Submit: Paul Irish <[email protected]>
Commit-Queue: Paul Irish <[email protected]>
Reviewed-by: Danil Somsikov <[email protected]>

Author: paulirish

front_end/core/host/InspectorFrontendHost.ts

@@ -486,6 +486,20 @@ export class InspectorFrontendHostStub implements InspectorFrontendHostAPI {
     throw new Error('Soft context menu should be used');
   }
 
+  /**
+   * **Hosted mode** is when DevTools is loaded over `http(s)://` rather than from `devtools://`.
+   * It does **not** indicate whether the frontend is connected to a valid CDP target.
+   *
+   *  | Example case                                         | Mode           | Example URL                                                                   |
+   *  | :--------------------------------------------------- | :------------- | :---------------------------------------------------------------------------- |
+   *  | typical devtools: (un)docked w/ native CDP bindings  | **NOT Hosted** | `devtools://devtools/bundled/devtools_app.html?targetType=tab&...`            |
+   *  | tab href is `devtools://…?ws=…`                      | **NOT Hosted** | `devtools://devtools/bundled/devtools_app.html?ws=localhost:9228/...`         |
+   *  | tab href is `devtools://…` but no connection         | **NOT Hosted** | `devtools://devtools/bundled/devtools_app.html`                               |
+   *  | tab href is `https://…?ws=` (connected)              | **Hosted**     | `https://chrome-devtools-frontend.appspot.com/serve_rev/@.../worker_app.html` |
+   *  | tab href is `http://…` but no connection             | **Hosted**     | `http://localhost:9222/devtools/inspector.html?ws=localhost:9222/...`         |
+   *
+   * See also `canDock` which has similar semantics.
+   */
   isHostedMode(): boolean {
     return true;
   }

front_end/core/root/Runtime.ts

@@ -11,6 +11,10 @@ let runtimePlatform = '';
 let runtimeInstance: Runtime|undefined;
 let isNode: boolean|undefined;
 
+/** Returns the base URL (similar to `<base>`).
+ * Used to resolve the relative URLs of any additional DevTools files (locale strings, etc) needed.
+ * See: https://cs.chromium.org/remoteBase+f:devtools_window
+ */
 export function getRemoteBase(location: string = self.location.toString()): {
   base: string,
   version: string,

front_end/core/sdk/Connections.ts

@@ -296,6 +296,7 @@ function createMainConnection(onConnectionLost: (message: Platform.UIString.Loca
     return new WebSocketConnection(ws, onConnectionLost);
   }
   if (Host.InspectorFrontendHost.InspectorFrontendHostInstance.isHostedMode()) {
+    // Hosted mode (e.g. `http://localhost:9222/devtools/inspector.html`) but no WebSocket URL.
     return new StubConnection();
   }
 

front_end/entrypoints/node_app/NodeMain.ts

@@ -44,6 +44,7 @@ export class NodeMainImpl implements Common.Runnable.Runnable {
     Host.userMetrics.actionTaken(Host.UserMetrics.Action.ConnectToNodeJSFromFrontend);
     void SDK.Connections.initMainConnection(async () => {
       const target = SDK.TargetManager.TargetManager.instance().createTarget(
+          // TODO: Use SDK.Target.Type.NODE rather thatn BROWSER once DevTools is loaded appropriately in that case.
           'main', i18nString(UIStrings.main), SDK.Target.Type.BROWSER, null);
       target.setInspectedURL('Node.js' as Platform.DevToolsPath.UrlString);
     }, Components.TargetDetachedDialog.TargetDetachedDialog.connectionLost);

front_end/ui/legacy/DockController.ts

@@ -123,6 +123,11 @@ export class DockController extends Common.ObjectWrapper.ObjectWrapper<EventType
     return this.dockSideInternal;
   }
 
+  /** Whether the DevTools can be docked, used to determine if we show docking UI.
+   * Set via `Root.Runtime.Runtime.queryParam('can_dock')`. See https://cs.chromium.org/can_dock+f:window
+   *
+   * Shouldn't be used as a heuristic for target connection state.
+   */
   canDock(): boolean {
     return this.canDockInternal;
   }