docs: Javadoc common module

common/src/main/java/jy95/fhir/common/bundle/MultiResourceBundle.java

@@ -2,12 +2,23 @@
 
 import java.util.*;
 
-// Credits to https://coiaf.de/java-multiple-resource-bundles/
-
+/**
+ * A ResourceBundle implementation that aggregates multiple ResourceBundles.
+ * This class allows retrieving values from a list of ResourceBundles,
+ * checking each bundle in the order they are provided.
+ */
 public class MultiResourceBundle extends ResourceBundle {
 
+    /**
+     * The list of delegate ResourceBundles used to retrieve resources.
+     */
     private final List<ResourceBundle> delegates;
 
+    /**
+     * Constructs a MultiResourceBundle with the specified list of ResourceBundles.
+     * @param resourceBundles the list of ResourceBundles to aggregate.
+     *                        If {@code null}, an empty list will be used.
+     */
     public MultiResourceBundle(List<ResourceBundle> resourceBundles) {
         this.delegates = resourceBundles == null ? new ArrayList<>() : resourceBundles;
     }

common/src/main/java/jy95/fhir/common/bundle/MultiResourceBundleControl.java

@@ -1,7 +1,5 @@
 package jy95.fhir.common.bundle;
 
-// Credits to https://coiaf.de/java-multiple-resource-bundles/
-
 import lombok.Getter;
 
 import java.io.IOException;
@@ -11,12 +9,28 @@
 import java.util.ResourceBundle;
 import java.util.stream.Collectors;
 
+/**
+ * A custom ResourceBundle.Control implementation that aggregates multiple ResourceBundles.
+ * This class facilitates the creation of a MultiResourceBundle by combining dependent ResourceBundles.
+ */
 @Getter
 public class MultiResourceBundleControl extends ResourceBundle.Control {
 
+    /**
+     * The base name of the primary ResourceBundle.
+     */
     private final String baseName;
+    /**
+     * The base names of dependent ResourceBundles to be aggregated.
+     */
     private final String[] dependentBaseNames;
 
+    /**
+     * Constructs a MultiResourceBundleControl with the specified base name and dependent base names.
+     *
+     * @param baseName          the base name of the primary ResourceBundle.
+     * @param dependentBaseNames the base names of additional ResourceBundles to aggregate.
+     */
     public MultiResourceBundleControl(String baseName, String... dependentBaseNames) {
         this.baseName = baseName;
         this.dependentBaseNames = dependentBaseNames;

common/src/main/java/jy95/fhir/common/bundle/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Configuration and default configuration values for the library.
+ * This package provides centralized management of settings
+ * and predefined defaults.
+ */
+package jy95.fhir.common.bundle;

common/src/main/java/jy95/fhir/common/config/DefaultImplementations.java

@@ -6,7 +6,17 @@
 
 import jy95.fhir.common.bundle.MultiResourceBundleControl;
 
+/**
+ * Provides default implementations for common operations in the library.
+ */
 public class DefaultImplementations {
+
+    /**
+     * Selects a ResourceBundle for the specified locale using a MultiResourceBundleControl.
+     *
+     * @param locale the locale for which the ResourceBundle is desired.
+     * @return the aggregated ResourceBundle for the specified locale.
+     */
     public static ResourceBundle selectResourceBundle(Locale locale) {
         var bundleControl = new MultiResourceBundleControl(
                 "translations",

common/src/main/java/jy95/fhir/common/config/FDSConfig.java

@@ -12,6 +12,9 @@
 
 import jy95.fhir.common.types.DisplayOrder;
 
+/**
+ * Configuration class for controlling how dosage are handled and displayed.
+ */
 @Getter
 @SuperBuilder
 public class FDSConfig {

common/src/main/java/jy95/fhir/common/config/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Configuration utilities for the FHIR library.
+ * Includes classes and methods to handle
+ * application-specific settings and dependencies.
+ */
+package jy95.fhir.common.config;

common/src/main/java/jy95/fhir/common/functions/AbstractFormatDateTimes.java

@@ -4,6 +4,10 @@
 import java.util.List;
 import java.util.Locale;
 
+/**
+ * Abstract base class for formatting DateTime objects into human-readable strings.
+ * @param <T> The type of the DateTime object to be formatted.
+ */
 public abstract class AbstractFormatDateTimes<T> {
 
     /**

common/src/main/java/jy95/fhir/common/functions/AbstractQuantityToString.java

@@ -9,10 +9,24 @@
 
 import jy95.fhir.common.config.FDSConfig;
 
+/**
+ * Abstract base class for converting quantity objects to human-readable strings.
+ * @param <C> The type of configuration object extending FDSConfig.
+ * @param <Q> The type of quantity object to be converted.
+ */
 public abstract class AbstractQuantityToString<C extends FDSConfig, Q> {
 
+    /**
+     * System URI for duration units in FHIR.
+     */
     final protected String DURATION_SYSTEM = "http://hl7.org/fhir/ValueSet/duration-units";
+    /**
+     * System URI for units of time in FHIR.
+     */
     final protected String UNITS_OF_TIME_SYSTEM = "http://hl7.org/fhir/ValueSet/units-of-time";
+    /**
+     * List of time-related systems.
+     */
     final protected List<String> TIME_SYSTEMS = List.of(DURATION_SYSTEM, UNITS_OF_TIME_SYSTEM);
 
     /**

common/src/main/java/jy95/fhir/common/functions/AbstractRangeToString.java

@@ -9,6 +9,11 @@
 
 import jy95.fhir.common.config.FDSConfig;
 
+/**
+ * Abstract base class for converting range objects to human-readable strings.
+ * @param <C> The type of configuration object extending FDSConfig.
+ * @param <R> The type of range object to be converted.
+ */
 public abstract class AbstractRangeToString<C extends FDSConfig, R> {
 
     /**

common/src/main/java/jy95/fhir/common/functions/AbstractRatioToString.java

@@ -7,6 +7,11 @@
 
 import jy95.fhir.common.config.FDSConfig;
 
+/**
+ * Abstract base class for converting ratio objects to human-readable strings.
+ * @param <C> The type of configuration object extending FDSConfig.
+ * @param <R> The type of ratio object to be converted.
+ */
 public abstract class AbstractRatioToString<C extends FDSConfig, R> {
 
     /**

common/src/main/java/jy95/fhir/common/functions/ListToString.java

@@ -3,10 +3,22 @@
 import java.util.List;
 import java.util.ResourceBundle;
 
+/**
+ * Utility class for converting a list of strings into a human-readable string.
+ */
 public final class ListToString {
 
+    /**
+     * Enum representing the link words used to combine list elements.
+     */
     public enum LinkWord {
-        AND("and"), 
+        /**
+         * Represents the "and" link word.
+         */
+        AND("and"),
+        /**
+         * Represents the "then" link word.
+         */
         THEN("then");
 
         private final String value;
@@ -15,11 +27,25 @@ public enum LinkWord {
             this.value = value;
         }
 
+        /**
+         * Retrieves the value of the link word.
+         *
+         * @return The string value of the link word.
+         */
         public String getValue() {
             return value;
         }
     }
 
+    /**
+     * Converts a list of strings into a human-readable string using a specified link word.
+     * Example: ["A", "B", "C"] with the link word "and" results in "A, B and C".
+     *
+     * @param bundle   The resource bundle for localization.
+     * @param list     The list of strings to convert.
+     * @param linkWord The link word to use for combining the elements.
+     * @return A human-readable string representation of the list.
+     */
     public static String convert(ResourceBundle bundle, List<String> list, LinkWord linkWord) {
 
         if (list.isEmpty()){
@@ -39,10 +65,25 @@ public static String convert(ResourceBundle bundle, List<String> list, LinkWord
         return firstString + linkWordString + lastString;
     }
 
+    /**
+     * Converts a list of strings into a human-readable string using the default link word "and".
+     * Example: ["A", "B", "C"] results in "A, B and C".
+     *
+     * @param bundle The resource bundle for localization.
+     * @param list   The list of strings to convert.
+     * @return A human-readable string representation of the list.
+     */
     public static String convert(ResourceBundle bundle, List<String> list) {
         return convert(bundle,list,LinkWord.AND);
     }
 
+    /**
+     * Retrieves the localized translation of the specified link word.
+     *
+     * @param bundle   The resource bundle for localization.
+     * @param linkWord The link word to translate.
+     * @return The translated link word as a string.
+     */
     private static String getLinkWordTranslation(ResourceBundle bundle, LinkWord linkWord) {
         // Delegate method for link word translation
         return bundle.getString("linkwords." + linkWord.getValue());

common/src/main/java/jy95/fhir/common/functions/SequenceUtils.java

@@ -7,8 +7,25 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
+/**
+ * A utility class for handling sequences of dosages.
+ * Provides methods for checking sequential instructions and grouping by sequence.
+ */
 public class SequenceUtils {
 
+    /**
+     * Checks if the given list of dosages contains only sequential instructions.
+     *
+     * <p>This method checks if the dosages contain unique sequence numbers,
+     * and determines if the instructions are sequential. A list of dosages is considered sequential
+     * if it either has no sequence numbers or has a sequence number for every dosage in the list.</p>
+     *
+     * @param dosages The list of dosages to check.
+     * @param getSequence A function that extracts the sequence number from each dosage.
+     * @param <T> The type of the dosage object.
+     * @return {@code true} if the dosages contain only sequential instructions,
+     *         {@code false} otherwise.
+     */
     public static <T> boolean containsOnlySequentialInstructions(List<T> dosages, Function<T, Integer> getSequence) {
         var encounteredSequenceNumbers = dosages
                 .stream()
@@ -19,6 +36,17 @@ public static <T> boolean containsOnlySequentialInstructions(List<T> dosages, Fu
         return encounteredSequenceNumbers.isEmpty() || encounteredSequenceNumbers.size() == dosages.size();
     }
 
+    /**
+     * Groups the given list of dosages by their sequence number.
+     *
+     * <p>This method creates a map of dosages grouped by sequence number,
+     * returning a list of lists where each inner list contains dosages with the same sequence number.</p>
+     *
+     * @param dosages The list of dosages to group.
+     * @param getSequence A function that extracts the sequence number from each dosage.
+     * @param <T> The type of the dosage object.
+     * @return A list of lists, where each inner list contains dosages grouped by their sequence number.
+     */
     public static <T> List<List<T>> groupBySequence(List<T> dosages, Function<T, Integer> getSequence) {
         Map<Integer, List<T>> sequencesMap = new HashMap<>();
 

common/src/main/java/jy95/fhir/common/functions/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Functional utilities and helpers for processing FHIR data.
+ * Contains reusable methods and functional interfaces for
+ * transforming and querying FHIR resources.
+ */
+package jy95.fhir.common.functions;

common/src/main/java/jy95/fhir/common/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Core functionality and shared utilities for the FHIR-related library.
+ * This package contains foundational classes and interfaces
+ * that are used across other packages.
+ */
+package jy95.fhir.common;

common/src/main/java/jy95/fhir/common/translators/AbstractAdditionalInstruction.java

@@ -7,12 +7,34 @@
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * An abstract class for translating "additionalInstruction".
+ *
+ * @param <C> The type of configuration, extending {@link FDSConfig}.
+ * @param <D> The type of the translated data.
+ */
 public abstract class AbstractAdditionalInstruction<C extends FDSConfig, D> extends AbstractTranslator<C, D> {
 
+    /**
+     * Constructor for {@code AbstractAdditionalInstruction}.
+     * @param config The configuration object used for translation.
+     */
     public AbstractAdditionalInstruction(C config) {
         super(config);
     }
 
+    /**
+     * Processes a list of asynchronous additional instructions and converts them to a single string.
+     *
+     * <p>This method waits for all the provided CompletableFuture instances to complete,
+     * collects their results as strings, and then uses {@link ListToString#convert}
+     * to combine them into a single string representation.</p>
+     *
+     * @param additionalInstructions A list of {@link CompletableFuture} objects representing
+     *                               the additional instructions to be processed.
+     * @return A {@link CompletableFuture} that, when completed, returns a string
+     *         representing all the additional instructions combined.
+     */
     protected CompletableFuture<String> instructionsFuture(
             List<CompletableFuture<String>> additionalInstructions
     ) {

common/src/main/java/jy95/fhir/common/translators/AbstractAsNeeded.java

@@ -5,13 +5,24 @@
 import jy95.fhir.common.config.FDSConfig;
 import jy95.fhir.common.types.AbstractTranslator;
 
+/**
+ * Abstract class for translating fields related to the "as needed" / "as needed for" concepts .
+ *
+ * @param <C> the type of configuration, which must extend {@link FDSConfig}
+ * @param <D> the type of data to be translated
+ */
 public abstract class AbstractAsNeeded<C extends FDSConfig, D> extends AbstractTranslator<C, D> {
 
     // Translations
+    /** MessageFormat instance used for "asNeededFor" translation. */
     protected final MessageFormat asNeededForMsg;
+    /** The message for "asNeeded". */
     protected final String asNeededMsg;
 
-    // Constructor passes the config to the superclass
+    /**
+     * Constructor for {@code AbstractAsNeeded}.
+     * @param config The configuration object used for translation.
+     */
     public AbstractAsNeeded(C config) {
         super(config);
         var bundle = getResources();

common/src/main/java/jy95/fhir/common/translators/AbstractBoundsDuration.java

@@ -5,12 +5,22 @@
 import jy95.fhir.common.config.FDSConfig;
 import jy95.fhir.common.types.AbstractTranslatorTiming;
 
+/**
+ * An abstract class for translating "timing.repeat.boundsDuration".
+ *
+ * @param <C> The type of configuration, extending {@link FDSConfig}.
+ * @param <D> The type of the translated data.
+ */
 public abstract class AbstractBoundsDuration<C extends FDSConfig, D> extends AbstractTranslatorTiming<C, D> {
 
     // Translations
+    /** MessageFormat instance used for "boundsDuration" translation. */
     protected final MessageFormat boundsDurationMsg;
 
-    // Constructor passes the config to the superclass
+    /**
+     * Constructor for {@code AbstractBoundsDuration}.
+     * @param config The configuration object used for translation.
+     */
     public AbstractBoundsDuration(C config) {
         super(config);
         String msg = getResources().getString("fields.boundsDuration");