Mark Dependency.optional as deprecated. (#2334)

* Mark Dependency.optional as deprecated.

* Apply suggestions from code review

Co-authored-by: Rodrigo Lazo <[email protected]>

Co-authored-by: Rodrigo Lazo <[email protected]>

Author: vkryachko

firebase-components/src/main/java/com/google/firebase/components/Dependency.java

@@ -47,30 +47,82 @@ private Dependency(Class<?> anInterface, @Type int type, @Injection int injectio
     this.injection = injection;
   }
 
+  /**
+   * Declares an optional dependency.
+   *
+   * <p>Optional dependencies can be missing at runtime(being {@code null}) and dependents must be
+   * ready to handle that.
+   *
+   * @deprecated Optional dependencies are not safe to use in the context of Play's dynamic feature
+   *     delivery. Use {@link #optionalProvider(Class) optional provider} instead.
+   */
+  @Deprecated
   public static Dependency optional(Class<?> anInterface) {
     return new Dependency(anInterface, Type.OPTIONAL, Injection.DIRECT);
   }
 
+  /**
+   * Declares a deferred dependency.
+   *
+   * <p>Such dependencies are optional and may not be present by default. But they can become
+   * available if a dynamic module that contains them is installed.
+   */
   public static Dependency deferred(Class<?> anInterface) {
     return new Dependency(anInterface, Type.OPTIONAL, Injection.DEFERRED);
   }
 
+  /**
+   * Declares a required dependency.
+   *
+   * <p>Such dependencies must be present in order for the dependent component to function. Any
+   * component with a required dependency should also declare a Maven dependency on an SDK that
+   * provides it. Failing to do so will result in a {@link MissingDependencyException} to be thrown
+   * at runtime.
+   */
   public static Dependency required(Class<?> anInterface) {
     return new Dependency(anInterface, Type.REQUIRED, Injection.DIRECT);
   }
 
+  /**
+   * Declares a Set multi-binding dependency.
+   *
+   * <p>Such dependencies provide access to a {@code Set<Foo>} to dependent components. Note that
+   * the set is only filled with components that explicitly declare the intent to be a "set"
+   * dependency via {@link Component#intoSet(Object, Class)}.
+   */
   public static Dependency setOf(Class<?> anInterface) {
     return new Dependency(anInterface, Type.SET, Injection.DIRECT);
   }
 
+  /**
+   * Declares an optional dependency.
+   *
+   * <p>Optional dependencies can be missing at runtime(being {@code null}) and dependents must be
+   * ready to handle that.
+   */
   public static Dependency optionalProvider(Class<?> anInterface) {
     return new Dependency(anInterface, Type.OPTIONAL, Injection.PROVIDER);
   }
 
+  /**
+   * Declares a required dependency.
+   *
+   * <p>Such dependencies must be present in order for the dependent component to function. Any
+   * component with a required dependency should also declare a Maven dependency on an SDK that
+   * provides it. Failing to do so will result in a {@link MissingDependencyException} to be thrown
+   * at runtime.
+   */
   public static Dependency requiredProvider(Class<?> anInterface) {
     return new Dependency(anInterface, Type.REQUIRED, Injection.PROVIDER);
   }
 
+  /**
+   * Declares a Set multi-binding dependency.
+   *
+   * <p>Such dependencies provide access to a {@code Set<Foo>} to dependent components. Note that
+   * the set is only filled with components that explicitly declare the intent to be a "set"
+   * dependency via {@link Component#intoSet(Object, Class)}.
+   */
   public static Dependency setOfProvider(Class<?> anInterface) {
     return new Dependency(anInterface, Type.SET, Injection.PROVIDER);
   }