Update code documentation.

Author: s-t-h

src/main/java/datastructure/Attributable.java

@@ -15,8 +15,6 @@
  * as key-value pairs in a {@link TreeMap}, allowing efficient retrieval, addition, extension, and removal
  * of attributes. It also supports operations like checking for the existence of attributes and converting
  * attributes to a string representation.
- *
- * @noinspection unused
  */
 public class Attributable {
 

src/main/java/datastructure/Contig.java

@@ -14,11 +14,9 @@
  * This class models a segment of a reference sequence, which can represent a complete genome,
  * a plasmid, a single contig, or a scaffold. It extends the {@link Attributable} class to
  * inherit functionality for managing attributes associated with the contig.
- * </p>
  * <p>
  * Each instance of this class is uniquely identified by its {@code name} and contains
  * information about its nucleotide sequence, variants, and other relevant properties.
- * </p>
  */
 public class Contig extends Attributable {
 
@@ -28,7 +26,6 @@ public class Contig extends Attributable {
      * This field uniquely identifies the contig within the context of the application.
      * It is a final field, meaning its value is immutable once assigned during the
      * construction of the {@link Contig} instance.
-     * </p>
      */
     public final String name;
 
@@ -38,10 +35,8 @@ public class Contig extends Attributable {
      * This field stores the nucleotide sequence of the contig. The sequence is expected to be
      * stored as a GZIP-compressed string to optimize storage. It may be empty or null if no
      * sequence is available for the contig.
-     * </p>
      * <p>
      * <b>Note:</b> The sequence is not validated against the variants stored in the {@code variants} map.
-     * </p>
      */
     protected final String sequence;
 
@@ -55,11 +50,9 @@ public class Contig extends Attributable {
      *     <li>The third level (value: {@link VariantInformation}) contains additional information about the variant,
      *         such as associations with {@link SequenceType}s or {@link Sample}s.</li>
      * </ul>
-     * </p>
      * <p>
      * This structure allows storage and retrieval of variant data, enabling queries by position,
      * alternative content, and associated metadata.
-     * </p>
      */
     protected final TreeMap<Integer, Map<String, VariantInformation>> variants;
 
@@ -69,11 +62,9 @@ public class Contig extends Attributable {
      * This field is a transient {@link HashMap} used to cache subsequences of the contig's sequence.
      * The keys in the map are {@link Tuple} objects representing the start and end positions of the subsequence,
      * and the values are the corresponding subsequences as {@link String}.
-     * </p>
      * <p>
      * The cache is transient because it is not intended to be serialized, as it is dynamically populated
      * during runtime to optimize performance by avoiding redundant sequence decompression or retrieval.
-     * </p>
      */
     protected transient HashMap<Tuple<Integer, Integer>, String> sequenceCache;
 
@@ -84,7 +75,6 @@ public class Contig extends Attributable {
      * initializes the {@link #variants} map to store variant information and the {@link #sequenceCache}
      * map to cache subsequences for optimized retrieval. The sequence is expected to be stored
      * as a GZIP-compressed string to reduce storage requirements.
-     * </p>
      *
      * @param name     The name or identifier of the contig.
      * @param sequence The nucleotide sequence of the contig, stored as a GZIP-compressed string.
@@ -103,7 +93,6 @@ protected Contig(String name, String sequence) {
      * This method determines whether the contig has a stored sequence by checking
      * if the {@code sequence} field is not empty. A non-empty sequence indicates
      * that the contig has an associated nucleotide sequence.
-     * </p>
      *
      * @return {@code true} if the contig has a sequence (i.e., the sequence length is not zero),
      * {@code false} otherwise.
@@ -117,7 +106,6 @@ public boolean hasSequence() {
      * <p>
      * This method decompresses the GZIP-compressed sequence stored in the {@code sequence} field
      * and returns it as a string. If no sequence is stored, it returns an empty string.
-     * </p>
      *
      * @return The decompressed nucleotide sequence of this contig, or an empty string if no sequence is stored.
      * @throws IOException If an error occurs during the decompression of the sequence.
@@ -136,12 +124,9 @@ public String getSequence() throws IOException {
      * specified start and end positions. The subsequence is cached to avoid redundant decompression
      * and substring operations for the same range. If the subsequence is already cached, it is
      * retrieved directly from the cache. Otherwise, it is computed, stored in the cache, and returned.
-     * </p>
-     *
      * <p>
      * The start and end positions are 1-based indices, meaning the first nucleotide in the sequence
      * is at position 1. If no sequence is stored for the contig, the method returns an empty string.
-     * </p>
      *
      * @param start The 1-based indexed start position of the subsequence (inclusive).
      * @param end   The 1-based indexed end position of the subsequence (exclusive).
@@ -169,7 +154,6 @@ public String getSubsequence(int start, int end) throws IOException {
      * This method iterates through the hierarchical map of variants stored in the {@code variants} field.
      * It computes the total count by summing up the sizes of all inner maps, where each inner map represents
      * the alternative sequences for a specific position on the contig.
-     * </p>
      *
      * @return The total number of variants located on this contig.
      */
@@ -184,7 +168,6 @@ public int getVariantsCount() {
      * for a variant located at the specified position with the given alternative bases. The returned
      * {@link VariantInformation} contains details about the variant, including its occurrences in
      * samples and features, as well as any associated attributes.
-     * </p>
      *
      * @param position         The 1-based position of the variant on the contig.
      * @param alternativeBases The alternative base sequence of the variant.
@@ -203,14 +186,11 @@ public VariantInformation getVariantInformation(int position, String alternative
      *   <li>The position of the variant (field {@code a} of the tuple).</li>
      *   <li>The alternate allele of the variant (field {@code b} of the tuple).</li>
      * </ul>
-     * </p>
-     *
      * <p>
      * For each variant, the method retrieves the associated {@link VariantInformation} using
      * the position and alternate allele. It then checks if the {@code Constants.EFFECTS} attribute
      * is present. If the attribute is found, its value (a comma-separated string of effects) is split
      * into individual effects, which are trimmed and aggregated into a {@link Set} to ensure uniqueness.
-     * </p>
      *
      * @param variants A list of {@link Tuple} objects representing the variants. Each tuple contains:
      *                 <ul>
@@ -236,7 +216,6 @@ public Set<String> getVariantsEffects(List<Tuple<Integer, String>> variants) {
      *   <li>The position of the variant on the contig.</li>
      *   <li>The alternative base sequence of the variant.</li>
      * </ul>
-     * </p>
      *
      * @return An {@link ArrayList} of {@link Tuple} objects, where each tuple contains
      * the position and alternative base sequence of a variant.
@@ -261,7 +240,6 @@ public ArrayList<Tuple<Integer, String>> getVariants() {
      *   <li>The position of the variant on the contig.</li>
      *   <li>The alternative base sequence of the variant.</li>
      * </ul>
-     * </p>
      *
      * @param start The 1-based indexed inclusive start position of the range.
      * @param end   The 1-based indexed inclusive end position of the range.
@@ -289,7 +267,6 @@ public ArrayList<Tuple<Integer, String>> getVariantsByLocation(int start, int en
      *   <li>The position of the variant on the contig.</li>
      *   <li>The alternative base sequence of the variant.</li>
      * </ul>
-     * </p>
      *
      * @param feature    The feature to filter variants by.
      * @param alleleUids A set of allele unique identifiers to filter variants by.
@@ -320,7 +297,6 @@ public ArrayList<Tuple<Integer, String>> getVariantsByAlleles(Feature feature, S
      *   <li>The position of the variant on the contig.</li>
      *   <li>The alternative base sequence of the variant.</li>
      * </ul>
-     * </p>
      *
      * @param sampleName The name of the sample to filter variants by.
      * @return An {@link ArrayList} of {@link Tuple} objects, where each tuple contains
@@ -349,7 +325,6 @@ public ArrayList<Tuple<Integer, String>> getVariantsBySample(String sampleName)
      *   <li>The position of the variant on the contig.</li>
      *   <li>The alternative base sequence of the variant.</li>
      * </ul>
-     * </p>
      *
      * @param sampleName The name of the sample to filter variants by.
      * @param start      The 1-based indexed inclusive start position of the location range.

src/main/java/datastructure/Feature.java

@@ -21,11 +21,9 @@
  * This class models a genomic feature, such as a gene, exon, or coding sequence (CDS),
  * that is analyzed in the context of genomic data processing. It extends the {@link Attributable}
  * class to inherit functionality for managing attributes associated with the feature.
- * </p>
  * <p>
  * Each instance of this class is uniquely identified by its {@code name} and contains
  * information about its type, location on the reference genome, and other relevant properties.
- * </p>
  */
 public class Feature extends Attributable {
 
@@ -35,11 +33,9 @@ public class Feature extends Attributable {
      * This field specifies the type of the feature, such as "gene", "exon", or "CDS".
      * The type is defined according to the GFF3 specification and provides information
      * about the biological or functional classification of the feature.
-     * </p>
      * <p>
      * For more details, refer to the GFF3 specification:
      * <a href="https://gmod.org/wiki/GFF3">https://gmod.org/wiki/GFF3</a>.
-     * </p>
      */
     public final String type;
 
@@ -49,7 +45,6 @@ public class Feature extends Attributable {
      * This field uniquely identifies the feature within the context of the analysis.
      * It is a final field, meaning its value is immutable once assigned during the
      * construction of the {@link Feature} instance.
-     * </p>
      */
     public final String name;
 
@@ -85,7 +80,6 @@ public class Feature extends Attributable {
      * a genomic feature. This class extends {@link SequenceType} and provides
      * functionality for managing alleles, including their unique identifiers,
      * variants, and attributes.
-     * </p>
      */
     public class Allele extends SequenceType {
 
@@ -117,7 +111,6 @@ private Allele(String uid, List<Tuple<Integer, String>> variants) {
      * from the genomic feature. This class extends {@link SequenceType} and provides
      * functionality for managing proteoforms, including their unique identifiers,
      * variants, and attributes.
-     * </p>
      */
     public class Proteoform extends SequenceType {
 
@@ -149,12 +142,10 @@ private Proteoform(String uid, List<Tuple<Integer, String>> variants) {
      * specific sequence variations of the feature. The keys in the map are unique
      * identifiers for the alleles, and the values are the corresponding {@link Allele}
      * instances.
-     * </p>
      * <p>
      * Alleles are used to track and manage sequence variations resulting from genomic
      * changes. Each allele is linked to its unique identifier and contains information
      * about its sequence and attributes.
-     * </p>
      */
     protected final HashMap<String, Allele> alleles = new HashMap<>();
 
@@ -165,11 +156,9 @@ private Proteoform(String uid, List<Tuple<Integer, String>> variants) {
      * specific sequence variants of proteins derived from the feature. The keys in the map
      * are unique identifiers for the proteoforms, and the values are the corresponding
      * {@link Proteoform} instances.
-     * </p>
      * <p>
      * Proteoforms are only relevant for coding features and are used to track and manage
      * protein sequence variations resulting from genomic changes.
-     * </p>
      */
     protected final HashMap<String, Proteoform> proteoforms = new HashMap<>();
 
@@ -179,7 +168,6 @@ private Proteoform(String uid, List<Tuple<Integer, String>> variants) {
      * This constructor initializes a genomic feature with its name, location, strand orientation,
      * type, and unique identifier. The feature's start and end positions are converted to integers
      * to ensure proper indexing. The {@link Attributable} superclass is also initialized.
-     * </p>
      *
      * @param name   The name of the feature, used as its internal identifier.
      * @param contig The name of the reference location (e.g., contig, chromosome, plasmid) where the feature is located.
@@ -302,9 +290,8 @@ public Collection<Allele> getAlleles() {
      * @throws MusialException          If an error occurs during sequence alignment or translation.
      * @throws IllegalArgumentException If the allele does not exist, the contig does not match the feature's contig,
      *                                  the contig lacks a sequence, the feature is not coding, or the variants map is empty.
-     * @noinspection UnusedReturnValue
      */
-    protected String updateProteoform(Contig contig, String alleleUid) throws IOException, MusialException {
+    protected void updateProteoform(Contig contig, String alleleUid) throws IOException, MusialException {
         // Check if the allele UID is valid.
         Allele allele = getAllele(alleleUid);
         if (allele == null)
@@ -403,8 +390,6 @@ protected String updateProteoform(Contig contig, String alleleUid) throws IOExce
 
         // Associate the allele with the proteoform.
         allele.setAttribute(Constants.$Allele_proteoform, proteoformUid);
-
-        return proteoformUid;
     }
 
     /**

src/main/java/datastructure/Sample.java

@@ -14,7 +14,6 @@
  * This class extends {@link Attributable} to inherit functionality for managing attributes.
  * It provides fields and methods to store and manipulate variant calls, alleles, and other
  * sample-specific data. Each instance of this class is uniquely identified by its {@code name}.
- * </p>
  */
 public class Sample extends Attributable {
 
@@ -24,7 +23,6 @@ public class Sample extends Attributable {
      * This field uniquely identifies the sample within the context of the application.
      * It is a final field, meaning its value is immutable once assigned during the
      * construction of the {@link Sample} instance.
-     * </p>
      */
     public final String name;
 
@@ -49,7 +47,6 @@ public class Sample extends Attributable {
      *         The format follows the <a href="https://samtools.github.io/hts-specs/VCFv4.2.pdf">VCFv4.2</a> specification.
      *     </li>
      * </ul>
-     * </p>
      */
     protected final HashMap<String, TreeMap<Integer, String>> variantCalls = new HashMap<>(2);
 
@@ -59,7 +56,6 @@ public class Sample extends Attributable {
      * This {@link Map} stores the relationship between feature names and their associated allele identifiers.
      * The keys represent the names of the features, and the values represent the unique identifiers of the alleles.
      * This structure is used to track which allele is associated with each feature in the sample.
-     * </p>
      */
     protected final Map<String, String> alleles;
 
@@ -77,7 +73,6 @@ public class Sample extends Attributable {
      *   <li>{@code REF_1:ALT_1:AD_1:PL_1,...}: One or more alternate alleles, each with their respective
      *       reference allele, alternate allele, allele depth, and phred-scaled likelihoods.</li>
      * </ul>
-     * </p>
      *
      * <pre>
      * Example match: {@code 1;13;99;TTC:.:0:585,TTC:T--:13:0}
@@ -92,7 +87,6 @@ public class Sample extends Attributable {
      * This constructor initializes a {@link Sample} object with the given name and allocates a {@link HashMap}
      * for the {@link #alleles} field with the specified initial capacity. The {@link #name} field is set to the
      * provided name, and the superclass constructor is invoked to initialize inherited properties.
-     * </p>
      *
      * @param name     The name of the sample, used as its unique identifier.
      * @param capacity The expected initial capacity of the {@link #alleles} map.
@@ -109,7 +103,6 @@ protected Sample(String name, int capacity) {
      * This method updates the {@link #alleles} map by setting the sequence type (allele)
      * for the specified feature. The feature is identified by its name, and the allele
      * is identified by its unique identifier.
-     * </p>
      *
      * @param featureName The name of the feature ({@link Feature#name}) to associate with the allele.
      * @param alleleUid   The unique identifier of the allele ({@link SequenceType#name}) to set for the feature.
@@ -124,7 +117,6 @@ protected void setAllele(String featureName, String alleleUid) {
      * This method looks up the allele identifier associated with the given feature name
      * in the {@link #alleles} map. If no allele is set for the specified feature, the method
      * returns the default reference value defined in {@link Constants#synonymous}.
-     * </p>
      *
      * @param featureName The name of the feature ({@link Feature#name}) to retrieve the associated allele identifier for.
      * @return The allele identifier ({@link Feature.Allele#_uid}) associated with the feature, or the reference value if not set.
@@ -139,7 +131,6 @@ public String getAllele(String featureName) {
      * This method returns a collection view of the mappings contained in the {@link #alleles} map.
      * Each entry in the collection represents a feature name and its associated allele identifier.
      * Modifications to the returned collection will reflect in the underlying map.
-     * </p>
      *
      * @return A {@link Collection} of {@link Map.Entry} objects representing the entries in the {@link #alleles} map.
      */
@@ -154,7 +145,6 @@ public Collection<Map.Entry<String, String>> getAlleles() {
      * The keys in the map represent the positions of the variants on the contig, and the values
      * are the corresponding variant call strings. If no variant calls exist for the specified
      * contig, an empty {@link TreeMap} is returned.
-     * </p>
      *
      * @param contig The name of the contig to retrieve the variant calls for.
      * @return A {@link TreeMap} where the keys are variant positions and the values are variant call strings.
@@ -170,7 +160,6 @@ public TreeMap<Integer, String> getVariantCalls(String contig) {
      * the reference base character from the starting position. The call string is expected to follow
      * the structure defined in {@link Sample#variantCallPattern}, where fields are separated by semicolons,
      * commas, and colons.
-     * </p>
      *
      * <pre>
      * Example call string: {@code 1;13;99;TTC:.:0:585,TTC:T--:13:0}
@@ -191,7 +180,6 @@ public static String getReferenceOfCall(String call) {
      * The attributes are formatted as key-value pairs separated by an equals sign (`=`) and delimited
      * by semicolons (`;`). If the last character of the generated string is a semicolon, it is removed
      * to ensure proper formatting.
-     * </p>
      *
      * @return A {@link String} representing the sample, including its name and attributes.
      */