Add some notes on WMShellBaseModule

Bug: 378565144
Flag: EXEMPT doc update
Test: Just updating docs
Change-Id: Id98327416f214e62def20c80ccafc0787b20be07

1 files changed, 50 insertions, 16 deletions

diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md
index 9b09904527bf..84525a741480 100644
--- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md
+++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md
@@ -1,4 +1,5 @@
 # Usage of Dagger in the Shell library
+
 [Back to home](README.md)
 
 ---
@@ -16,36 +17,69 @@ As such, the Shell also tries to provide some reasonable out-of-the-box modules
 ## Modules
 
 All the Dagger related code in the Shell can be found in the `com.android.wm.shell.dagger` package,
-this is intentional as it keeps the "magic" in a single location.  The explicit nature of how
+this is intentional as it keeps the "magic" in a single location. The explicit nature of how
 components in the shell are provided is as a result a bit more verbose, but it makes it easy for
 developers to jump into a few select files and understand how different components are provided
 (especially as products override components).
 
 The module dependency tree looks a bit like:
+
 - [WMShellConcurrencyModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java)
   (provides threading-related components)
-  - [WMShellBaseModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellBaseModule.java)
-    (provides components that are likely common to all products, ie. DisplayController,
-    Transactions, etc.)
-    - [WMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellModule.java)
-      (phone/tablet specific components only)
-    - [TvPipModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvPipModule.java)
-      (PIP specific components for TV)
-      - [TvWMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvWMShellModule.java)
-        (TV specific components only)
-  - etc.
+    - [WMShellBaseModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellBaseModule.java)
+      (provides components that are common to many products, ie. DisplayController, Transactions,
+      etc.)
+        - [WMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellModule.java)
+          (phone/tablet specific components only)
+        - [TvPipModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvPipModule.java)
+          (PIP specific components for TV)
+            - [TvWMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvWMShellModule.java)
+              (TV specific components only)
+    - etc.
 
 Ideally features could be abstracted out into their own modules and included as needed by each
 product.
 
+## Changing WMShellBaseModule
+
+Because all products will include WMShellBaseModule, we don't want it to provide instances for
+features that aren't used across multiple products (ie. Handheld, TV, Auto, Wear). This module
+should generally only provide:
+
+- Concrete implementations that are needed for startup
+  (see `provideIndependentShellComponentsToCreate()`)
+- Things used directly/indirectly by interfaces
+  exposed to SysUI
+  in [WMComponent.java](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMComponent.java).
+
+For the latter, not every feature will be enabled on the SysUI form factor including the base
+module, so the recommendation is to have an `@BindsOptionalOf` for the interface, and have the
+actual implementation provided in the form-factor specific module (ie. `WMShellModule`).
+
 ## Overriding base components
 
 In some rare cases, there are base components that can change behavior depending on which
-product it runs on.  If there are hooks that can be added to the component, that is the
+product it runs on. If there are hooks that can be added to the component, that is the
 preferable approach.
 
-The alternative is to use the [@DynamicOverride](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/DynamicOverride.java)
+The alternative is to use
+the [@DynamicOverride](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/DynamicOverride.java)
 annotation to allow the product module to provide an implementation that the base module can
-reference.  This is most useful if the existence of the entire component is controlled by the
-product and the override implementation is optional (there is a default implementation).  More
-details can be found in the class's javadoc.
\ No newline at end of file
+reference. This is most useful if the existence of the entire component is controlled by the
+product and the override implementation is optional (there is a default implementation). More
+details can be found in the class's javadoc.
+
+## Starting up Shell components aren't dependencies for other components
+
+With Dagger, objects are created in dependency order and individual components can register with
+`ShellInit` (see [Component initialization](changes.md#component-initialization)) to initialize in
+dependency order as well. However, if there is code that needs to run on startup but has nothing
+dependent on it (imagine a background error detector for example), then
+`provideIndependentShellComponentsToCreate()` can serve as the artificial dependent object (itself
+a dependency for `ShellInterface`) to trigger creation of such a component.
+
+This can be declared within each module, so if a product includes `WMShellModule`, all the
+components in `provideIndependentShellComponentsToCreate()` for both it and `WMShellBaseModule` will
+be created.
+
+Note that long term we are looking to move to a `CoreStartable` like infrastructure.
\ No newline at end of file