Remove incorrect Doubleton deprecation - no Kotlin stdlib equivalent (#19)

* Remove incorrect Doubleton deprecation - no Kotlin stdlib equivalent exists

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com>

Author: Copilot

CLAUDE.md

@@ -959,18 +959,16 @@ None. All critical bugs identified by SonarQube have been fixed.
 
 **Recommendation:** Review with domain expert if high-precision rendering is required.
 
-#### DEFERRED-003: Doubleton Missing equals() Override
+#### RESOLVED: Doubleton equals() Override
 
-**Severity:** Minor (SonarQube rule java:S1206)
-**File:** `src/main/java/cz/vutbr/fit/interlockSim/util/Doubleton.java` (line 85)
+**Status:** RESOLVED (equals() override added during Kotlin migration)
+**File:** `src/main/kotlin/cz/vutbr/fit/interlockSim/util/Doubleton.kt` (line 110)
 
-**Description:** Class overrides `hashCode()` but not `equals()`, violating the hashCode/equals contract.
+**Description:** Class now properly overrides both `hashCode()` and `equals()`, satisfying the contract.
 
-**Impact:** Potential incorrect behavior when Doubleton objects are used in hash-based collections.
+**Resolution:** The equals() method was added during Kotlin migration. Additionally, the incorrect `@Deprecated` annotation was removed after analysis showed that Doubleton has no equivalent in Kotlin's standard library. Kotlin's `Pair` is ordered (A,B ≠ B,A), while Doubleton is unordered (A,B = B,A) and supports associated values, making it essential for representing bidirectional graph edges.
 
-**Workaround:** Doubleton class is marked `@Deprecated`. Avoid using in new code.
-
-**Recommendation:** Replace Doubleton with modern alternatives (e.g., `Map.Entry`, records) in future modernization.
+**Documentation:** Updated KDoc explains why Doubleton cannot be replaced with Kotlin's Pair.
 
 ### Design Limitations
 
@@ -1048,8 +1046,9 @@ The codebase has been analyzed for deprecated Java standard library APIs. This i
   - Easy fix: Use `Integer.valueOf()` or autoboxing
 
 **MEDIUM Priority:**
-- Internal project classes marked deprecated (`Doubleton`, `TreeMultiMap`) - 55 occurrences
+- Internal project classes marked deprecated (`TreeMultiMap`) - ~27 occurrences
   - These are project-specific deprecations, not Java SE
+  - Note: `Doubleton` deprecation was removed after analysis showed no Kotlin stdlib equivalent
   - Require design review to determine replacement strategy
 
 ### Monitoring

src/main/kotlin/cz/vutbr/fit/interlockSim/util/Doubleton.kt

@@ -13,17 +13,31 @@ import java.util.AbstractSet
 import java.util.NoSuchElementException
 
 /**
- * Pair of nodes for implementation ADT ExtendedUnorientedGraph
- * Represents combination of two elements
- * @param <T> type of elements
- * @param <V> type of additional information
+ * Unordered pair of nodes for implementation ADT ExtendedUnorientedGraph.
  *
- * @deprecated should be replaced in kotlin with library thing like Pair
+ * Represents an unordered combination of two distinct elements with associated values.
+ * Unlike Kotlin's [Pair], this class provides **order-independent equality**:
+ * `Doubleton(A, B) == Doubleton(B, A)`.
+ *
+ * **Key Features:**
+ * - Extends [AbstractSet] providing set semantics
+ * - Enforces element distinctness (first != second)
+ * - Order-independent equality and commutative hashCode
+ * - Associated values for each element accessible via [getValue]
+ * - Mutable values via [setValues]
+ * - Suitable as HashMap key with proper hash-based collection behavior
+ *
+ * **Why not use Kotlin's Pair?**
+ * - [Pair] is ordered: `Pair(A, B) != Pair(B, A)`
+ * - [Pair] has no associated values mechanism
+ * - [Pair] is not a Set and doesn't enforce distinctness
+ *
+ * This class is essential for representing unordered edges in graph structures where
+ * the relationship between nodes is bidirectional and order-independent.
+ *
+ * @param T type of elements (the two nodes)
+ * @param V type of additional information associated with each element
  */
-@Deprecated(
-	message = "Should be replaced in kotlin with library thing like Pair",
-	replaceWith = ReplaceWith("Pair<T, V>")
-)
 class Doubleton<T, V> : AbstractSet<T> {
 	enum class IteratorState {
 		INIT,
@@ -63,21 +77,25 @@ class Doubleton<T, V> : AbstractSet<T> {
 	private var secondValue: V? = null
 
 	/**
-	 * Create with additional information
-	 * @param first
-	 * @param second
-	 * @param firstValue
-	 * @param secondValue
+	 * Creates a Doubleton with associated values for each element.
+	 *
+	 * @param first the first element
+	 * @param second the second element (must be distinct from first)
+	 * @param firstValue the value associated with the first element
+	 * @param secondValue the value associated with the second element
+	 * @throws IllegalArgumentException if first equals second
 	 */
 	constructor(first: T, second: T, firstValue: V, secondValue: V) : this(first, second) {
 		this.firstValue = firstValue
 		this.secondValue = secondValue
 	}
 
 	/**
-	 * Create without additional information
-	 * @param first
-	 * @param second
+	 * Creates a Doubleton without initial associated values.
+	 *
+	 * @param first the first element
+	 * @param second the second element (must be distinct from first)
+	 * @throws IllegalArgumentException if first equals second
 	 */
 	constructor(first: T, second: T) {
 		if (first == second) throw IllegalArgumentException("arguments is equal")
@@ -120,8 +138,11 @@ class Doubleton<T, V> : AbstractSet<T> {
 	override fun isEmpty(): Boolean = false
 
 	/**
-	 * @param key
-	 * @return value assigned to key
+	 * Retrieves the value associated with the specified element.
+	 *
+	 * @param key the element whose associated value is to be returned
+	 * @return the value associated with the key, or null if no value has been set
+	 * @throws IllegalArgumentException if the key is not contained in this Doubleton
 	 */
 	fun getValue(key: T): V? {
 		val secondEq = nullEq(key, second)
@@ -142,8 +163,10 @@ class Doubleton<T, V> : AbstractSet<T> {
 	}
 
 	/**
-	 * @param first
-	 * @param second
+	 * Sets the associated values for both elements.
+	 *
+	 * @param first the value to associate with the first element
+	 * @param second the value to associate with the second element
 	 */
 	fun setValues(
 		first: V,