Add documentation for dagger.useBindingGraphFix compiler option.

In addition to adding documentation, this CL changes the compiler option name from `useLegacyBindingGraphFactory` to `useBindingGraphFix` to flip the default (it's more intuitive when disabled means "old behavior" and enabled means "new behavior") and to give the name more meaning from a user's perspective (useLegacyBindingGraphFactory likely doesn't mean much for users).

RELNOTES=N/A
PiperOrigin-RevId: 713020394

Author: bcorso

java/dagger/internal/codegen/binding/LegacyBindingGraphFactory.java

@@ -70,7 +70,7 @@ public final class LegacyBindingGraphFactory {
 
   static boolean useLegacyBindingGraphFactory(
       CompilerOptions compilerOptions, ComponentDescriptor componentDescriptor) {
-    return compilerOptions.useLegacyBindingGraphFactory();
+    return !compilerOptions.useBindingGraphFix();
   }
 
   static boolean hasStrictMultibindingsExemption(

java/dagger/internal/codegen/compileroption/CompilerOptions.java

@@ -119,24 +119,14 @@ public final boolean doCheckForNulls() {
   public abstract boolean generatedClassExtendsComponent();
 
   /**
-   * Returns {@code true} if Dagger should use the legacy binding graph factory.
+   * Returns {@code true} if Dagger should turn on the binding graph fix.
    *
-   * <p>Note: This flag is only intended to give users time to migrate to the new binding graph
-   * factory. New users should not enable this flag. This flag will be removed in a future release.
+   * <p>Note: This flag is only intended to give users time to migrate. This flag will be removed in
+   * a future release.
    *
-   * <p>The legacy binding graph factory contains a number of bugs which can lead to an incorrect
-   * binding graph (e.g. missing multibindings), can be difficult to debug, and are often dependent
-   * on the ordering of bindings/dependency requests in the user's code.
-   *
-   * <p>The new binding graph factory fixes many of these issues by switching to a well known graph
-   * data structure and algorithms to avoid many of the subtle bugs that plagued the legacy binding
-   * graph factory. However, note that the new binding graph factory also has a behavior change that
-   * could cause issues for some users. Specifically, a module binding is no longer allowed to float
-   * from its installed component into one of its subcomponents in order to satisfy a missing
-   * dependency. Thus, any (transitive) dependencies of the module binding that are missing from the
-   * installed component will now be reported as an error.
+   * <p>See https://dagger.dev/dev-guide/compiler-options#useBindingGraphFix for more details.
    */
-  public abstract boolean useLegacyBindingGraphFactory();
+  public abstract boolean useBindingGraphFix();
 
   /**
    * Returns {@code true} if the key for map multibinding contributions contain a framework type.

java/dagger/internal/codegen/compileroption/ProcessingEnvironmentCompilerOptions.java

@@ -34,8 +34,8 @@
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.PLUGINS_VISIT_FULL_BINDING_GRAPHS;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.STRICT_MULTIBINDING_VALIDATION;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.STRICT_SUPERFICIAL_VALIDATION;
+import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.USE_BINDING_GRAPH_FIX;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.USE_FRAMEWORK_TYPE_IN_MAP_MULTIBINDING_CONTRIBUTION_KEY;
-import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.USE_LEGACY_BINDING_GRAPH_FACTORY;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.VALIDATE_TRANSITIVE_COMPONENT_DEPENDENCIES;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.WARN_IF_INJECTION_FACTORY_NOT_GENERATED_UPSTREAM;
 import static dagger.internal.codegen.compileroption.ProcessingEnvironmentCompilerOptions.Feature.WRITE_PRODUCER_NAME_IN_TOKEN;
@@ -205,8 +205,8 @@ public boolean generatedClassExtendsComponent() {
   }
 
   @Override
-  public boolean useLegacyBindingGraphFactory() {
-    return isEnabled(USE_LEGACY_BINDING_GRAPH_FACTORY);
+  public boolean useBindingGraphFix() {
+    return isEnabled(USE_BINDING_GRAPH_FIX);
   }
 
   @Override
@@ -342,7 +342,7 @@ enum Feature implements EnumOption<FeatureStatus> {
 
     GENERATED_CLASS_EXTENDS_COMPONENT,
 
-    USE_LEGACY_BINDING_GRAPH_FACTORY(ENABLED),
+    USE_BINDING_GRAPH_FIX,
 
     USE_FRAMEWORK_TYPE_IN_MAP_MULTIBINDING_CONTRIBUTION_KEY,
 

java/dagger/internal/codegen/javac/JavacPluginCompilerOptions.java

@@ -112,8 +112,8 @@ public boolean experimentalDaggerErrorMessages() {
   }
 
   @Override
-  public boolean useLegacyBindingGraphFactory() {
-    return true;
+  public boolean useBindingGraphFix() {
+    return false;
   }
 
   @Override