Strengthen class & function documentation in CompositeLFSR.java (TheAlgorithms#5596)

Hardvan · alxkm · web-flow · commit ee6cd648bc4e · 2024-10-06T20:12:57.000+02:00
Co-authored-by: Alex Klymenko &lt;alexanderklmn@gmail.com&gt;
diff --git a/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java b/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java
@@ -5,13 +5,33 @@
 import java.util.Map;
 import java.util.TreeMap;
 
+/**
+ * The CompositeLFSR class represents a composite implementation of
+ * Linear Feedback Shift Registers (LFSRs) for cryptographic purposes.
+ *
+ * <p>
+ * This abstract class manages a collection of LFSR instances and
+ * provides a mechanism for irregular clocking based on the
+ * majority bit among the registers. It implements the BaseLFSR
+ * interface, requiring subclasses to define specific LFSR behaviors.
+ * </p>
+ */
 public abstract class CompositeLFSR implements BaseLFSR {
 
     protected final List<LFSR> registers = new ArrayList<>();
 
     /**
-     * Implements irregular clocking using the clock bit for each register
-     * @return the registers discarded bit xored value
+     * Performs a clocking operation on the composite LFSR.
+     *
+     * <p>
+     * This method determines the majority bit across all registers and
+     * clocks each register based on its clock bit. If a register's
+     * clock bit matches the majority bit, it is clocked (shifted).
+     * The method also computes and returns the XOR of the last bits
+     * of all registers.
+     * </p>
+     *
+     * @return the XOR value of the last bits of all registers.
      */
     @Override
     public boolean clock() {
@@ -26,6 +46,18 @@ public boolean clock() {
         return result;
     }
 
+    /**
+     * Calculates the majority bit among all registers.
+     *
+     * <p>
+     * This private method counts the number of true and false clock bits
+     * across all LFSR registers. It returns true if the count of true
+     * bits is greater than or equal to the count of false bits; otherwise,
+     * it returns false.
+     * </p>
+     *
+     * @return true if the majority clock bits are true; false otherwise.
+     */
     private boolean getMajorityBit() {
         Map<Boolean, Integer> bitCount = new TreeMap<>();
         bitCount.put(Boolean.FALSE, 0);
