[MARTIFACT-44] improve documentation

Author: hboutemy

src/it/flatten/invoker.properties renamed to src/it/compare-flatten/invoker.properties

@@ -15,5 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
+# initial reference build: install
 invoker.goals.1=clean install
-invoker.goals.2=clean package artifact:compare
+# second build: verify (could be package, but not install to avoid overriding reference)
+invoker.goals.2=clean verify artifact:compare

src/it/flatten/modA/pom.xml renamed to src/it/compare-flatten/modA/pom.xml

@@ -15,6 +15,8 @@
 # specific language governing permissions and limitations
 # under the License.
 
+# initial reference build: install
 invoker.goals.1=clean install
+# second build: package (could be verify, but not install to avoid overriding reference)
 invoker.goals.2=clean package artifact:compare
 invoker.buildResult.2=failure

src/it/flatten/modB/pom.xml renamed to src/it/compare-flatten/modB/pom.xml

@@ -29,7 +29,7 @@
 import org.apache.maven.project.MavenProjectHelper;
 
 /**
- * Creates a buildinfo file recording build environment and output, as specified in
+ * Creates a buildinfo file recording build environment and output (from {@code package}), as specified in
  * <a href="https://reproducible-builds.org/docs/jvm/">Reproducible Builds for the JVM</a>
  * for mono-module build, and extended for multi-module build.
  */

src/it/flatten/pom.xml renamed to src/it/compare-flatten/pom.xml

@@ -46,8 +46,8 @@
 import org.eclipse.aether.repository.RemoteRepository;
 
 /**
- * Compare current build output with reference either previously installed or downloaded from a remote repository:
- * results go to {@code .buildcompare} file.
+ * Compare current build output (from {@code package}) against reference either previously {@code install}-ed or downloaded from a remote
+ * repository: comparison results go to {@code .buildcompare} file.
  *
  * @since 3.2.0
  */
@@ -68,7 +68,7 @@ public class CompareMojo extends AbstractBuildinfoMojo {
     private String referenceRepo;
 
     /**
-     * Compare aggregate only (ie wait for the last module) or do buildcompare on each module.
+     * Compare aggregate only (ie wait for the last module) or also compare on each module.
      * @since 3.2.0
      */
     @Parameter(property = "compare.aggregate.only", defaultValue = "false")
@@ -124,7 +124,7 @@ protected void skip(MavenProject last) throws MojoExecutionException {
     /**
      * Check current build result with reference.
      *
-     * @artifacts a Map of artifacts added to the build info with their associated property key prefix
+     * @param artifacts a Map of artifacts added to the build info with their associated property key prefix
      *            (<code>outputs.[#module.].#artifact</code>)
      * @throws MojoExecutionException
      */

src/it/flatten/verify.groovy renamed to src/it/compare-flatten/verify.groovy

@@ -32,11 +32,11 @@ ${project.name}
 
 * Goals Overview
 
-  The Artifact Plugin only has 3 goals currently:
+  The Artifact Plugin has 3 goals currently:
 
-  * {{{./buildinfo-mojo.html}artifact:buildinfo}} records current build results in {{{https://reproducible-builds.org/docs/jvm/}Reproducible Builds buildinfo}} file,
+  * {{{./buildinfo-mojo.html}artifact:buildinfo}} records current build results (from <<<package>>>) in {{{https://reproducible-builds.org/docs/jvm/}Reproducible Builds buildinfo}} file,
 
-  * {{{./compare-mojo.html}artifact:compare}} compares current build output against reference build previously published,
+  * {{{./compare-mojo.html}artifact:compare}} compares current build output (from <<<package>>>) against reference build previously published,
 
   * {{{./check-buildplan-mojo.html}artifact:check-buildplan}} checks the project's buildplan to find if any used {{{./plugin-issues.html}plugin has a known Reproducible Builds issue}}.