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

Co-authored-by: Alex Klymenko <alexanderklmn@gmail.com>
This commit is contained in:
Hardik Pawar
2024-10-06 23:42:57 +05:30
committed by GitHub
parent afc06d5632
commit ee6cd648bc

View File

@ -5,13 +5,33 @@ import java.util.List;
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 abstract class CompositeLFSR implements BaseLFSR {
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);