Update documentation

- javadocs for annotation
- migration in getting-started
- info about deprecation

Author: slawekjaranowski

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/Basedir.java

@@ -18,15 +18,39 @@
  */
 package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Mojo parameters container
+ * Specifies the base directory for test resources in Maven plugin tests.
+ * This annotation can be applied to test methods to define where test resources are located.
+ *
+ ** <p>Example usage:</p>
+ * <pre>
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ *     @Test
+ *     @Basedir("src/test/resources/specific-test-case")
+ *     @InjectMojo(goal = "compile")
+ *     void testSpecificCase(MyMojo mojo) {
+ *         // Test resources will be loaded from src/test/resources/specific-test-case
+ *         mojo.execute();
+ *     }
+ * }
+ * }
+ * </pre>
+ *
+ * @see MojoTest
+ * @see MojoExtension
+ * @since 3.4.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
+@Target(ElementType.METHOD)
 public @interface Basedir {
     String value() default "";
 }

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java

@@ -18,15 +18,71 @@
  */
 package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
+ * Annotation used in Maven plugin tests to inject and configure a Mojo instance.
+ * This annotation can be applied to either test methods or parameters to specify
+ * which Mojo should be instantiated and how it should be configured.
  *
+ * <p>The annotation requires a {@code goal} attribute to specify which Mojo goal
+ * should be instantiated. Optionally, a custom {@code pom} file can be specified
+ * to provide specific configuration for the test.</p>
+ *
+ * <p>Example usage on a test method:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * void testCompileMojo(CompileMojo mojo) {
+ *     mojo.execute();
+ *     // verify compilation results
+ * }
+ * }
+ * </pre>
+ *
+ * <p>Example usage with a custom POM:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(
+ *     goal = "compile",
+ *     pom = "src/test/resources/test-pom.xml"
+ * )
+ * void testCompileMojoWithCustomConfig(CompileMojo mojo) {
+ *     mojo.execute();
+ *     // verify compilation results
+ * }
+ * }
+ * </pre>
+ *
+ * <p>The annotation can be used in conjunction with {@link MojoParameter} to provide
+ * specific parameter values for the Mojo:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * void testCompileMojoWithParameters(CompileMojo mojo) {
+ *     mojo.execute();
+ *     // verify compilation results
+ * }
+ * }
+ * </pre>
+ *
+ * @see MojoTest
+ * @see MojoParameter
+ * @see MojoExtension
+ * @since 3.4.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
+@Target(ElementType.METHOD)
 public @interface InjectMojo {
 
     String goal();

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java

@@ -93,12 +93,45 @@
 import static org.mockito.Mockito.mockingDetails;
 
 /**
- * JUnit's extension to help testing Mojos. The extension should be automatically registered
- * by adding the {@link MojoTest} annotation on the test class.
+ * JUnit Jupiter extension that provides support for testing Maven plugins (Mojos).
+ * This extension handles the lifecycle of Mojo instances in tests, including instantiation,
+ * configuration, and dependency injection.
+ *
+ * <p>The extension is automatically registered when using the {@link MojoTest} annotation
+ * on a test class. It provides the following features:</p>
+ * <ul>
+ *   <li>Automatic Mojo instantiation based on {@link InjectMojo} annotations</li>
+ *   <li>Parameter injection using {@link MojoParameter} annotations</li>
+ *   <li>POM configuration handling</li>
+ *   <li>Project stub creation and configuration</li>
+ *   <li>Maven session and build context setup</li>
+ *   <li>Component dependency injection</li>
+ * </ul>
+ *
+ * <p>Example usage in a test class:</p>
+ * <pre>
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ *     @Test
+ *     @InjectMojo(goal = "my-goal")
+ *     @MojoParameter(name = "outputDirectory", value = "${project.build.directory}/generated")
+ *     void testMojoExecution(MyMojo mojo) throws Exception {
+ *         mojo.execute();
+ *         // verify execution results
+ *     }
+ * }
+ * }
+ * </pre>
+ **
+ * <p>For custom POM configurations, you can specify a POM file using the {@link InjectMojo#pom()}
+ * attribute. The extension will merge this configuration with default test project settings.</p>*
  *
  * @see MojoTest
  * @see InjectMojo
  * @see MojoParameter
+ * @see Basedir
+ * @since 3.4.0
  */
 public class MojoExtension extends PlexusExtension implements ParameterResolver {
 

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java

@@ -18,17 +18,58 @@
  */
 package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Mojo parameter
+ * Specifies a parameter value for a Mojo in a Maven plugin test.
+ * This annotation can be used to configure individual Mojo parameters
+ * without requiring a full POM file.
+ *
+ * <p>The annotation is repeatable, allowing multiple parameters to be set
+ * on a single test method or parameter. For multiple parameters, you can
+ * either use multiple {@code @MojoParameter} annotations or a single
+ * {@link MojoParameters} annotation.</p>
+ *
+ * <p>Example usage with a single parameter:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * void testCompilation(CompileMojo mojo) {
+ *     mojo.execute();
+ * }
+ * }
+ * </pre>
+ *
+ * <p>Example usage with multiple parameters:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * @MojoParameter(name = "debug", value = "true")
+ * void testCompilation(CompileMojo mojo) {
+ *     mojo.execute();
+ * }
+ * }
+ * </pre>
+ *
+ * @see MojoParameters
+ * @see InjectMojo
+ * @see MojoTest
+ * @since 3.4.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Repeatable(MojoParameters.class)
 @Inherited
+@Target(ElementType.METHOD)
 public @interface MojoParameter {
     String name();
 

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java

@@ -18,15 +18,59 @@
  */
 package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Mojo parameters container
+ * Container annotation for multiple {@link MojoParameter} annotations.
+ * This annotation is automatically used by Java when multiple {@code @MojoParameter}
+ * annotations are applied to the same element.
+ *
+ * <p>While this annotation can be used directly, it's generally more convenient
+ * to use multiple {@code @MojoParameter} annotations, which Java will automatically
+ * wrap in this container annotation.</p>
+ *
+ * <p>Example of direct usage:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameters({
+ *     @MojoParameter(name = "source", value = "1.8"),
+ *     @MojoParameter(name = "target", value = "1.8"),
+ *     @MojoParameter(name = "debug", value = "true")
+ * })
+ * void testCompilation(CompileMojo mojo) {
+ *     mojo.execute();
+ * }
+ * }
+ * </pre>
+ *
+ * <p>Equivalent usage with repeatable annotation:</p>
+ * <pre>
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * @MojoParameter(name = "debug", value = "true")
+ * void testCompilation(CompileMojo mojo) {
+ *     mojo.execute();
+ * }
+ * }
+ * </pre>
+ *
+ * @see MojoParameter
+ * @see InjectMojo
+ * @see MojoTest
+ * @since 3.4.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
+@Target(ElementType.METHOD)
 public @interface MojoParameters {
     MojoParameter[] value();
 }

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java

@@ -18,15 +18,67 @@
  */
 package org.apache.maven.api.plugin.testing;
 
+import javax.inject.Inject;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.apache.maven.api.di.Provides;
 import org.junit.jupiter.api.extension.ExtendWith;
 
 /**
+ * Annotation that enables Maven plugin (Mojo) testing support in JUnit tests.
+ * When applied to a test class, it automatically sets up the testing environment
+ * for Maven plugins, including dependency injection and parameter resolution.
+ *
+ * <p>This annotation works in conjunction with {@link InjectMojo} and {@link MojoParameter}
+ * to provide a comprehensive testing framework for Maven plugins. It automatically registers
+ * the {@link MojoExtension} which handles the plugin lifecycle and dependency injection.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ *     @Inject
+ *     private SomeComponent component;
+ *
+ *     @Test
+ *     @InjectMojo(goal = "my-goal")
+ *     @MojoParameter(name = "parameter", value = "value")
+ *     void testMojoExecution(MyMojo mojo) {
+ *         // mojo is instantiated with the specified parameters
+ *         // component is automatically injected
+ *         mojo.execute();
+ *         // verify execution results
+ *     }
+ *
+ *     @Provides
+ *     SomeComponent provideMockedComponent() {
+ *         return mock(SomeComponent.class);
+ *     }
+ * }
+ * }
+ * </pre>
+ *
+ * <p>The annotation supports:</p>
+ * <ul>
+ *   <li>Automatic Mojo instantiation and configuration</li>
+ *   <li>Parameter injection via {@link MojoParameter}</li>
+ *   <li>Component injection via {@link Inject}</li>
+ *   <li>Mock component injection via {@link Provides}</li>
+ *   <li>Custom POM configuration via {@link InjectMojo#pom()}</li>
+ *   <li>Base directory configuration for test resources via {@link Basedir}</li>
+ * </ul>
+ *
  *
+ * @see MojoExtension
+ * @see InjectMojo
+ * @see MojoParameter
+ * @see Provides
+ * @since 4.0.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @ExtendWith(MojoExtension.class)

maven-plugin-testing-harness/src/site/markdown/examples/artifact.md

@@ -21,6 +21,12 @@ date: February 2008
 ## Testing Project Artifact
 
 
+### NOTE
+
+`JUnit 3` based tests are deprecated since `3.4.0`.
+
+Use JUnit 5 annotations, consult [javadocs](../apidocs/org/apache/maven/api/plugin/testing/package-summary.html) for examples.
+
  **Note**: This example improves the [cookbook](../getting-started/index.html) to play with artifact handler.
 
 

maven-plugin-testing-harness/src/site/markdown/examples/complex-mojo-parameters.md

@@ -20,6 +20,11 @@ date: February 2008
 <!--  under the License. -->
 ## Testing Complex Mojo Parameters
 
+### NOTE
+
+`JUnit 3` based tests are deprecated since `3.4.0`.
+
+Use JUnit 5 annotations, consult [javadocs](../apidocs/org/apache/maven/api/plugin/testing/package-summary.html) for examples.
 
  **Note**: This example improves the [cookbook](../getting-started/index.html) for testing complex Mojo parameters.
 

maven-plugin-testing-harness/src/site/markdown/examples/multiproject.md

@@ -20,6 +20,11 @@ date: February 2008
 <!--  under the License. -->
 ## Testing Multiproject
 
+### NOTE
+
+`JUnit 3` based tests are deprecated since `3.4.0`.
+
+Use JUnit 5 annotations, consult [javadocs](../apidocs/org/apache/maven/api/plugin/testing/package-summary.html) for examples.
 
  **Note**: This example improves the [cookbook](../getting-started/index.html) for multi-project testing.
 

maven-plugin-testing-harness/src/site/markdown/examples/repositories.md

@@ -20,6 +20,11 @@ date: February 2008
 <!--  under the License. -->
 ## Testing Using Repositories
 
+### NOTE
+
+`JUnit 3` based tests are deprecated since `3.4.0`.
+
+Use JUnit 5 annotations, consult [javadocs](../apidocs/org/apache/maven/api/plugin/testing/package-summary.html) for examples.
 
  **Note**: This example improves the [cookbook](../getting-started/index.html) for testing repositories.