Add javadoc to DI (#2072)

Author: gnodet

api/maven-api-di/src/main/java/org/apache/maven/api/di/Inject.java

@@ -27,6 +27,32 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Marks a dependency injection point for constructor, method, or field injection.
+ * <p>
+ * This annotation is used to identify injection points where the container should
+ * provide an instance of the requested type. It can be applied to:
+ * <ul>
+ *   <li>Constructors</li>
+ *   <li>Methods</li>
+ *   <li>Fields</li>
+ * </ul>
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class MyService {
+ *     private final Repository repository;
+ *
+ *     {@literal @}Inject
+ *     public MyService(Repository repository) {
+ *         this.repository = repository;
+ *     }
+ * }
+ * </pre>
+ *
+ * @see Named
+ * @since 4.0.0
+ */
 @Target({FIELD, CONSTRUCTOR, METHOD})
 @Retention(RUNTIME)
 @Documented

api/maven-api-di/src/main/java/org/apache/maven/api/di/Named.java

@@ -23,9 +23,37 @@
 
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Provides a unique identifier for dependencies when multiple implementations
+ * of the same type are available.
+ * <p>
+ * This annotation can be used in conjunction with {@link Inject} to specify
+ * which implementation should be injected when multiple candidates exist.
+ * The value represents a unique identifier for the dependency.
+ * <p>
+ * Example usage:
+ * <pre>
+ * {@literal @}Inject
+ * {@literal @}Named("mysql")
+ * private Repository mysqlRepository;
+ * </pre>
+ *
+ * @see Inject
+ * @see Qualifier
+ * @since 4.0.0
+ */
 @Qualifier
 @Retention(RUNTIME)
 @Documented
 public @interface Named {
+    /**
+     * The name identifier for the annotated element.
+     * <p>
+     * If no value is specified, the default empty string will be used.
+     * When used as a qualifier, this value helps distinguish between different
+     * implementations or instances of the same type.
+     *
+     * @return the name that identifies this component
+     */
     String value() default "";
 }

api/maven-api-di/src/main/java/org/apache/maven/api/di/Priority.java

@@ -26,9 +26,39 @@
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Specifies the priority of a bean implementation when multiple implementations
+ * of the same type are available.
+ * <p>
+ * Higher values indicate higher priority. When multiple implementations of the same
+ * type exist, the one with the highest priority will be selected for injection.
+ * <p>
+ * Example usage:
+ * <pre>
+ * {@literal @}Priority(100)
+ * public class PreferredImplementation implements Service {
+ *     // Implementation
+ * }
+ * </pre>
+ *
+ * @since 4.0.0
+ */
 @Target({TYPE, METHOD})
 @Retention(RUNTIME)
 @Documented
 public @interface Priority {
+    /**
+     * The priority value for the annotated element.
+     * <p>
+     * Higher values indicate higher priority. When multiple implementations
+     * of the same type exist in the container, the one with the highest
+     * priority value will be selected for injection.
+     * <p>
+     * There are no predefined minimum or maximum values, but it's recommended
+     * to use values that allow for future adjustments (e.g., using values
+     * like 100, 200, 300 rather than consecutive numbers).
+     *
+     * @return the priority value for ordering
+     */
     int value();
 }

api/maven-api-di/src/main/java/org/apache/maven/api/di/Provides.java

@@ -26,7 +26,25 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Can be used on a static method to provide a bean.
+ * Marks a method as a provider of beans for dependency injection.
+ * <p>
+ * This annotation can be used on static methods to programmatically create and configure
+ * beans that will be managed by the dependency injection container. It's particularly
+ * useful when the bean creation requires complex logic or when the bean needs to be
+ * configured based on runtime conditions.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class Providers {
+ *     {@literal @}Provides
+ *     {@literal @}Singleton
+ *     public static Configuration provideConfiguration() {
+ *         return Configuration.load();
+ *     }
+ * }
+ * </pre>
+ *
+ * @since 4.0.0
  */
 @Target(METHOD)
 @Retention(RUNTIME)

api/maven-api-di/src/main/java/org/apache/maven/api/di/Qualifier.java

@@ -25,6 +25,25 @@
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Meta-annotation that marks other annotations as qualifier annotations.
+ * <p>
+ * Qualifiers are used to distinguish between multiple beans of the same type,
+ * allowing for more precise control over which implementation should be injected.
+ * Custom qualifier annotations should be annotated with {@code @Qualifier}.
+ * <p>
+ * Example of creating a custom qualifier:
+ * <pre>
+ * {@literal @}Qualifier
+ * {@literal @}Retention(RUNTIME)
+ * public @interface Database {
+ *     String value();
+ * }
+ * </pre>
+ *
+ * @see Named
+ * @since 4.0.0
+ */
 @Target(ANNOTATION_TYPE)
 @Retention(RUNTIME)
 @Documented

api/maven-api-di/src/main/java/org/apache/maven/api/di/Scope.java

@@ -25,6 +25,24 @@
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Meta-annotation that marks other annotations as scope annotations.
+ * <p>
+ * Scopes define the lifecycle and visibility of objects in the dependency injection
+ * system. Custom scope annotations should be annotated with {@code @Scope}.
+ * <p>
+ * Built-in scopes include:
+ * <ul>
+ *   <li>{@link Singleton} - One instance per container</li>
+ *   <li>{@link SessionScoped} - One instance per Maven session</li>
+ *   <li>{@link MojoExecutionScoped} - One instance per plugin execution</li>
+ * </ul>
+ *
+ * @see Singleton
+ * @see SessionScoped
+ * @see MojoExecutionScoped
+ * @since 4.0.0
+ */
 @Target(ANNOTATION_TYPE)
 @Retention(RUNTIME)
 @Documented

api/maven-api-di/src/main/java/org/apache/maven/api/di/Singleton.java

@@ -23,6 +23,24 @@
 
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Denotes that a bean should be created as a singleton instance.
+ * <p>
+ * Singleton-scoped beans are instantiated once and reused throughout the entire
+ * Maven execution. This scope should be used for stateless services or components
+ * that can be safely shared across the entire build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * {@literal @}Singleton
+ * public class GlobalConfiguration {
+ *     // Implementation
+ * }
+ * </pre>
+ *
+ * @see Scope
+ * @since 4.0.0
+ */
 @Scope
 @Documented
 @Retention(RUNTIME)

api/maven-api-di/src/main/java/org/apache/maven/api/di/Typed.java

@@ -27,9 +27,44 @@
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Explicitly specifies the types that should be used for dependency injection.
+ * <p>
+ * This annotation allows you to limit which types of a bean should be available
+ * for injection. It can be used to prevent unintended automatic binding of implemented
+ * interfaces or extended classes.
+ * <p>
+ * Example usage:
+ * <pre>
+ * {@literal @}Typed(ServiceImpl.class)
+ * public class ServiceImpl implements Service {
+ *     // Implementation
+ * }
+ * </pre>
+ *
+ * @since 4.0.0
+ */
 @Target({FIELD, METHOD, TYPE})
 @Retention(RUNTIME)
 @Documented
 public @interface Typed {
+    /**
+     * Specifies the types that should be considered for dependency injection.
+     * <p>
+     * When specified, only the listed types will be available for injection,
+     * even if the class implements or extends other types. If empty, the
+     * default behavior is to make all supertypes available for injection.
+     * <p>
+     * Example:
+     * <pre>
+     * {@literal @}Typed({Service.class, Monitored.class})
+     * public class ServiceImpl implements Service, Monitored, Logging {
+     *     // Only Service and Monitored will be available for injection,
+     *     // Logging interface will be ignored
+     * }
+     * </pre>
+     *
+     * @return an array of classes that should be considered for injection
+     */
     Class<?>[] value() default {};
 }

api/maven-api-di/src/main/java/org/apache/maven/api/di/package-info.java

@@ -0,0 +1,21 @@
+/**
+ * A dependency injection framework for Maven that provides JSR-330 style annotations
+ * for managing object lifecycle and dependencies within Maven's build process.
+ * <p>
+ * This package provides a set of annotations that control how objects are created,
+ * managed and injected throughout Maven's execution lifecycle. The framework is designed
+ * to be lightweight yet powerful, supporting various scopes of object lifecycle from
+ * singleton instances to mojo-execution-scoped beans.
+ * <p>
+ * Key features include:
+ * <ul>
+ *   <li>Constructor, method, and field injection</li>
+ *   <li>Qualifiers for distinguishing between beans of the same type</li>
+ *   <li>Multiple scopes (Singleton, Session, and MojoExecution)</li>
+ *   <li>Priority-based implementation selection</li>
+ *   <li>Type-safe dependency injection</li>
+ * </ul>
+ *
+ * @since 4.0.0
+ */
+package org.apache.maven.api.di;