doc: enhance documentation in ProvenanceManager for clarity and consistency

Author: Pfeil

src/main/java/edu/kit/datamanager/ro_crate/writer/ProvenanceManager.java

@@ -14,7 +14,19 @@
  * Handles the creation and updating of ro-crate-java entity and its actions.
  */
 public class ProvenanceManager {
+    /**
+     * A record to hold the prefix for the ro-crate-java ID.
+     * This is used to ensure that the ID is consistent across different versions of the library.
+     * Having a type for the prefix avoids using it by accident as a full ID.
+     */
     protected record IdPrefix(String prefix) {
+        /**
+         * Constructs a String with the given suffix.
+         *
+         * @param suffix The suffix to append to the prefix.
+         * @return A String combining the prefix and suffix, separated by a hyphen.
+         *         Like this: "$prefix-$suffix".
+         */
         public String withSuffix(String suffix) {
             return prefix + "-" + suffix;
         }
@@ -25,8 +37,16 @@ public String toString() {
         }
     }
 
+    /**
+     * The prefix for the ro-crate-java ID.
+     * This is used to identify the ro-crate-java entity in the crate.
+     */
     protected static final IdPrefix RO_CRATE_JAVA_ID_PREFIX = new IdPrefix("#ro-crate-java");
 
+    /**
+     * The VersionProvider used to retrieve the version of ro-crate-java.
+     * This allows for flexibility in how the version is determined, e.g., from a properties file.
+     */
     protected VersionProvider versionProvider;
 
     /**
@@ -45,11 +65,25 @@ public ProvenanceManager(VersionProvider versionProvider) {
         this.versionProvider = versionProvider;
     }
 
+    /**
+     * Returns the full ID for the ro-crate-java entity of this library version
+     * to be used for an entity describing it.
+     * <p>
+     * The ID is constructed using the RO_CRATE_JAVA_ID_PREFIX and the version from the VersionProvider.
+     *
+     * @return The ID for the ro-crate-java entity.
+     */
     public String getLibraryId() {
         return RO_CRATE_JAVA_ID_PREFIX.withSuffix(versionProvider.getVersion().toLowerCase());
     }
 
-    protected void addProvenanceInformation(Crate crate) {
+    /**
+     * Adds provenance information to the given crate.
+     * This includes creating or updating the ro-crate-java entity and its associated action entity.
+     *
+     * @param crate The crate to which provenance information will be added.
+     */
+    public void addProvenanceInformation(Crate crate) {
         // Determine if this is the first write
         boolean isFirstWrite = crate.getAllContextualEntities().stream().noneMatch(
                 entity -> entity.getId().startsWith(RO_CRATE_JAVA_ID_PREFIX.toString()))
@@ -58,7 +92,7 @@ protected void addProvenanceInformation(Crate crate) {
         String libraryId = this.getLibraryId();
 
         // Create action entity first
-        ContextualEntity actionEntity = createActionEntity(isFirstWrite, libraryId);
+        ContextualEntity actionEntity = buildNewActionEntity(isFirstWrite, libraryId);
 
         // Create or update ro-crate-java entity
         ContextualEntity roCrateJavaEntity = buildRoCrateJavaEntity(crate, actionEntity.getId(), libraryId);
@@ -68,7 +102,7 @@ protected void addProvenanceInformation(Crate crate) {
         crate.addContextualEntity(actionEntity);
     }
 
-    protected ContextualEntity createActionEntity(boolean isFirstWrite, String libraryId) {
+    protected ContextualEntity buildNewActionEntity(boolean isFirstWrite, String libraryId) {
         return new ContextualEntityBuilder()
                 .addType(isFirstWrite ? "CreateAction" : "UpdateAction")
                 .addIdProperty("result", "./")