Updated docs

phax · Apr 11, 2024 · 605591b · 605591b
1 parent 104b794
commit 605591b
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 5 deletions.
diff --git a/ph-diver-api/src/main/java/com/helger/diver/api/version/IPseudoVersionComparable.java b/ph-diver-api/src/main/java/com/helger/diver/api/version/IPseudoVersionComparable.java
@@ -29,7 +29,23 @@
  */
 public interface IPseudoVersionComparable
 {
+  /**
+   * Compare this object to the provided pseudo version.
+   *
+   * @param aOtherPseudoVersion
+   *        The pseudo version to compare to. Never <code>null</code>.
+   * @return a value &lt; 0 if this is &lt; other version; value 0 if this =
+   *         other version; value &gt; 0 if this is &gt; other version
+   */
   int compareToPseudoVersion (@Nonnull IVESPseudoVersion aOtherPseudoVersion);
 
-  int compareToVersion (@Nonnull Version aStaticVersion);
+  /**
+   * Compare this object to the provided static version.
+   *
+   * @param aOtherStaticVersion
+   *        The static version to compare to. Never <code>null</code>.
+   * @return a value &lt; 0 if this is &lt; other version; value 0 if this =
+   *         other version; value &gt; 0 if this is &gt; other version
+   */
+  int compareToVersion (@Nonnull Version aOtherStaticVersion);
 }
diff --git a/ph-diver-api/src/main/java/com/helger/diver/api/version/IVESPseudoVersionRegistry.java b/ph-diver-api/src/main/java/com/helger/diver/api/version/IVESPseudoVersionRegistry.java
@@ -20,6 +20,8 @@
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.NotThreadSafe;
 
+import com.helger.commons.state.EChange;
+
 /**
  * Base interface for a Pseudo version registry.
  *
@@ -29,9 +31,24 @@
 @NotThreadSafe
 public interface IVESPseudoVersionRegistry
 {
+  /**
+   * Register the provided pseudo version.
+   *
+   * @param aPseudoVersion
+   *        The pseudo version to register. Must not be <code>null</code>.
+   * @return {@link EChange#CHANGED} if it was added, {@link EChange#UNCHANGED}
+   *         if it was already present. Never <code>null</code>.
+   */
   @Nonnull
-  IVESPseudoVersion registerPseudoVersion (@Nonnull IVESPseudoVersion aPseudoVersion);
+  EChange registerPseudoVersion (@Nonnull IVESPseudoVersion aPseudoVersion);
 
+  /**
+   * Try to resolve the pseudo version with the provided ID.
+   *
+   * @param sID
+   *        The pseudo version ID to look up.
+   * @return <code>null</code> if no such pseudo version is present.
+   */
   @Nullable
   IVESPseudoVersion getFromIDOrNull (@Nullable String sID);
 }
diff --git a/ph-diver-api/src/main/java/com/helger/diver/api/version/VESPseudoVersionRegistry.java b/ph-diver-api/src/main/java/com/helger/diver/api/version/VESPseudoVersionRegistry.java
@@ -30,6 +30,7 @@
 import com.helger.commons.collection.impl.ICommonsMap;
 import com.helger.commons.hashcode.HashCodeGenerator;
 import com.helger.commons.lang.ServiceLoaderHelper;
+import com.helger.commons.state.EChange;
 import com.helger.commons.string.ToStringGenerator;
 import com.helger.commons.version.Version;
 import com.helger.diver.api.version.spi.IVESPseudoVersionRegistrarSPI;
@@ -121,15 +122,18 @@ public final void reinitialize ()
   }
 
   @Nonnull
-  public IVESPseudoVersion registerPseudoVersion (@Nonnull final IVESPseudoVersion aPseudoVersion)
+  public EChange registerPseudoVersion (@Nonnull final IVESPseudoVersion aPseudoVersion)
   {
     ValueEnforcer.notNull (aPseudoVersion, "PseudoVersion");
 
     final String sKey = aPseudoVersion.getID ();
     if (m_aPVs.containsKey (sKey))
-      throw new IllegalArgumentException ("Another pseudoversion with ID '" + sKey + "' is already registered");
+    {
+      LOGGER.error ("Another pseudoversion with ID '" + sKey + "' is already registered");
+      return EChange.UNCHANGED;
+    }
     m_aPVs.put (sKey, aPseudoVersion);
-    return aPseudoVersion;
+    return EChange.CHANGED;
   }
 
   @Nullable