From 9845c00a9f96085a3e3f9981201d367d97d08667 Mon Sep 17 00:00:00 2001
From: Andreas Huber <andreas.huber@lucares.de>
Date: Sun, 27 Apr 2025 10:15:35 +0200
Subject: [PATCH] improve documentation

---
 .../collections/MultiwayLongMerger.java       | 44 +++++++++++++------
 1 file changed, 30 insertions(+), 14 deletions(-)

diff --git a/primitiveCollections/src/main/java/org/lucares/collections/MultiwayLongMerger.java b/primitiveCollections/src/main/java/org/lucares/collections/MultiwayLongMerger.java
index 2cc5561..1ac3112 100644
--- a/primitiveCollections/src/main/java/org/lucares/collections/MultiwayLongMerger.java
+++ b/primitiveCollections/src/main/java/org/lucares/collections/MultiwayLongMerger.java
@@ -106,6 +106,12 @@ class MultiwayLongMerger {
 		}
 	}
 
+	/**
+	 * Returns the next power of two that is equal or larger than i.
+	 * or more formally: x where x = 2^n and x >= i for n ∈ ℕ and n minimal
+	 * @param i some positive integer
+	 * @return smallest integer that is a power of two and equal or larger than i
+	 */
 	private static int nextPowOfTwo(int i) {
 		return Integer.highestOneBit(i - 1) << 1;
 	}
@@ -164,22 +170,32 @@ class MultiwayLongMerger {
 		}
 
 		/**
+		 * A heap is a tree where the value of the parent is smaller than the value of its children.
 		 * <pre>
-		 *               7
-		 *           3  
-		 *               8
-		 *       1   
-		 *               9
-		 *           4
-		 *               10
-		 *   0
-		 *               11
-		 *           5
-		 *               12
-		 *       2
-		 *               13
-		 *           6 
+		 *               23
+		 *           13  
 		 *               14
+		 *       9   
+		 *               37
+		 *           24
+		 *               77
+		 *   5
+		 *               44
+		 *           35
+		 *               93
+		 *       7
+		 *               29
+		 *           27 
+		 *               31       ┌────────────────────────┬────┐
+		 *                   ┌────┼──────────────┬────┐    │    │
+		 *    ┌────┬────┐    │    │              │    │    │    │
+		 * ┏━━┷━┳━━━━┳━━━━┳━━┷━┳━━┷━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
+		 * ┃  5 ┃  9 ┃  7 ┃ 13 ┃ 24 ┃ 35 ┃ 27 ┃ 23 ┃ 14 ┃ 37 ┃ 77 ┃ 93 ┃ 29 ┃ 31 ┃
+		 * ┗━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┻━━━━┛
+		 *    0    1    2    3    4    5    6    7    8    9   10   11   12   13  (array indices)
+		 *         │    │    │    │    │    │
+		 *         └────┼────┴────┘    │    │
+		 *              └──────────────┴────┘           
 		 * </pre>
 		 */
 		private void init() {