#979: Merged with upstream

Author: andrzejj0

versions-common/pom.xml

@@ -188,10 +188,8 @@
       <plugin>
         <artifactId>maven-javadoc-plugin</artifactId>
         <configuration>
-          <!-- Exclude packages generated by Modello in JavaDocs -->
-          <excludePackageNames>org.codehaus.mojo.versions.model,
-            org.codehaus.mojo.versions.model.io.stax,
-            org.codehaus.mojo.versions.utils</excludePackageNames>
+          <!-- sources contain both generated model and non-generated classes -->
+          <doclint>all,-missing</doclint>
         </configuration>
       </plugin>
     </plugins>

versions-common/src/main/java/org/codehaus/mojo/versions/api/AbstractVersionDetails.java

@@ -89,11 +89,7 @@ public static boolean isPreReleaseVersion(String version) {
     protected boolean verboseDetail = true;
 
     /**
-     * <<<<<<< HEAD
      * Creates a new, empty instance.
-     * =======
-     * Creates a new instance
-     * >>>>>>> 55436036 (#979: overhaul of the updates logger; added json and csv + a new appendable xml which records multiple executions)
      */
     protected AbstractVersionDetails() {}
 

versions-common/src/main/java/org/codehaus/mojo/versions/recording/ChangeRecorderRenderer.java

@@ -11,7 +11,21 @@
  * @since 2.20.0
  */
 public interface ChangeRecorderRenderer {
+    /**
+     * Reads the change log from the given path.
+     *
+     * @param path the path to read from
+     * @return the read change log
+     * @throws IOException if an I/O error occurs
+     */
     ChangeRecorderLog read(Path path) throws IOException;
 
+    /**
+     * Writes the change log to the given path.
+     *
+     * @param path the path to write to
+     * @param log the change log to write
+     * @throws IOException if an I/O error occurs
+     */
     void write(Path path, ChangeRecorderLog log) throws IOException;
 }

versions-common/src/main/java/org/codehaus/mojo/versions/recording/CsvVersionChangeRecorderFactory.java

@@ -16,6 +16,11 @@
  */
 @Named("csv")
 public class CsvVersionChangeRecorderFactory implements VersionChangeRecorderFactory {
+    /**
+     * Create a new instance.
+     */
+    public CsvVersionChangeRecorderFactory() {}
+
     @Override
     public synchronized VersionChangeRecorder create(
             MavenSession mavenSession, MojoExecution mojoExecution, Map<String, String> changeRendererOptions) {

versions-common/src/main/java/org/codehaus/mojo/versions/recording/JsonVersionChangeRecorderFactory.java

@@ -16,6 +16,11 @@
  */
 @Named("json")
 public class JsonVersionChangeRecorderFactory implements VersionChangeRecorderFactory {
+    /**
+     * Create a new instance
+     */
+    public JsonVersionChangeRecorderFactory() {}
+
     @Override
     public synchronized VersionChangeRecorder create(
             MavenSession mavenSession, MojoExecution mojoExecution, Map<String, String> changeRendererOptions) {

versions-common/src/main/java/org/codehaus/mojo/versions/recording/NoneVersionChangeRecorderFactory.java

@@ -12,8 +12,18 @@
 import org.codehaus.mojo.versions.api.recording.VersionChangeRecorderFactory;
 import org.codehaus.mojo.versions.model.VersionChange;
 
+/**
+ * A {@link VersionChangeRecorderFactory} that creates a no-op {@link VersionChangeRecorder}.
+ * This implementation does not record any changes or write any report.
+ * It can be used when version change recording is not desired.
+ */
 @Named("none")
 public class NoneVersionChangeRecorderFactory implements VersionChangeRecorderFactory {
+    /**
+     * Creates a new instance
+     */
+    public NoneVersionChangeRecorderFactory() {}
+
     @Override
     public VersionChangeRecorder create(
             MavenSession mavenSession, MojoExecution mojoExecution, Map<String, String> changeRendererOptions) {

versions-common/src/main/java/org/codehaus/mojo/versions/recording/VersionChangeFileHelper.java

@@ -4,7 +4,23 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+/**
+ * Helper class for file operations related to version change recording.
+ *
+ * @since 2.20.0
+ */
 public class VersionChangeFileHelper {
+    private VersionChangeFileHelper() {
+        // utility class
+    }
+
+    /**
+     * Creates a file at the specified path, including any necessary but nonexistent parent directories.
+     * If the file already exists, no action is taken.
+     *
+     * @param path the path of the file to create
+     * @throws IOException if an I/O error occurs
+     */
     public static void createFile(Path path) throws IOException {
         Path parent = path.getParent();
         if (parent != null) {

versions-common/src/main/java/org/codehaus/mojo/versions/recording/XmlVersionChangeRecorderFactory.java

@@ -16,9 +16,24 @@
 /**
  * A {@link VersionChangeRecorderFactory} for rendering the updates into the format compatible
  * with the legacy {@code http://www.mojohaus.org/versions-maven-plugin/schema/updates/2.0} schema
+ * and the current {@code http://www.mojohaus.org/versions-maven-plugin/schema/updates/3.0} schema.
+ * The choice of the schema version is controlled by the {@code legacy} option:
+ * <ul>
+ * <li>If the {@code legacy} option is not provided or set to {@code true
+ * (ignoring case)}, the legacy schema is used.</li>
+ * <li>If the {@code legacy} option is set to {@code false} (ign
+ * oring case), the current schema is used.</li>
+ * </ul>
+ *
+ * @since 2.20.0
  */
 @Named("xml")
 public class XmlVersionChangeRecorderFactory implements VersionChangeRecorderFactory {
+    /**
+     * Create a new instance
+     */
+    public XmlVersionChangeRecorderFactory() {}
+
     @Override
     public VersionChangeRecorder create(
             MavenSession mavenSession, MojoExecution mojoExecution, Map<String, String> options) {

versions-common/src/main/java/org/codehaus/mojo/versions/recording/csv/ChangeRecorderLogCsvDeserializer.java

@@ -16,10 +16,22 @@
 import org.codehaus.mojo.versions.model.VersionsExecution;
 import org.codehaus.mojo.versions.model.xjb.ZonedDateTimeXmlAdapter;
 
+/**
+ * A CSV deserializer for {@link ChangeRecorderLog}.
+ *
+ * @since 2.20.0
+ */
 public class ChangeRecorderLogCsvDeserializer extends StdDeserializer<ChangeRecorderLog> {
-
+    /**
+     * The object factory to use to create model instances.
+     */
     private final ObjectFactory objectFactory;
 
+    /**
+     * Creates a new deserializer.
+     *
+     * @param objectFactory the object factory to use to create model instances
+     */
     public ChangeRecorderLogCsvDeserializer(ObjectFactory objectFactory) {
         super(VersionsExecution.class);
         this.objectFactory = objectFactory;

versions-common/src/main/java/org/codehaus/mojo/versions/recording/csv/ChangeRecorderLogCsvModule.java

@@ -4,7 +4,18 @@
 import org.codehaus.mojo.versions.model.ChangeRecorderLog;
 import org.codehaus.mojo.versions.model.ObjectFactory;
 
+/**
+ * A Jackson module for CSV serialization and deserialization of {@link ChangeRecorderLog}.
+ * It registers the appropriate serializer and deserializer.
+ *
+ * @since 2.20.0
+ */
 public class ChangeRecorderLogCsvModule extends SimpleModule {
+    /**
+     * Creates a new module.
+     *
+     * @param objectFactory the object factory to use to create model instances during deserialization
+     */
     public ChangeRecorderLogCsvModule(ObjectFactory objectFactory) {
         addSerializer(ChangeRecorderLog.class, new ChangeRecorderLogCsvSerializer());
         addDeserializer(ChangeRecorderLog.class, new ChangeRecorderLogCsvDeserializer(objectFactory));