From 04099dafe1fc239baf097de50b367acb18e80409 Mon Sep 17 00:00:00 2001
From: "eric.jarosch" <eric.jarosch@nexus-ag.de>
Date: Wed, 23 Sep 2026 15:38:20 +0200
Subject: [PATCH 1/2] add javadoc to Cursor#add and Cursor#addEol

---
 src/main/java/org/codejive/properties/Cursor.java | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/main/java/org/codejive/properties/Cursor.java b/src/main/java/org/codejive/properties/Cursor.java
index bf355cd..403e99d 100644
--- a/src/main/java/org/codejive/properties/Cursor.java
+++ b/src/main/java/org/codejive/properties/Cursor.java
@@ -145,12 +145,24 @@ public int prevCount(Predicate<PropertiesParser.Token> accept) {
         return cnt;
     }
 
+    /**
+     * Inserts a token at the current position, pushing the current token (if any) forwards.
+     * <br/>
+     * This method advances the cursor by one token (causing it to point at the initial token again).
+     * @param token the token to insert.
+     * @return {@code this}
+     */
     public Cursor add(PropertiesParser.Token token) {
         index = Math.max(index, 0);
         addToken(index++, token);
         return this;
     }
 
+    /**
+     * Inserts an EOL Token at the current position.
+     * @see #add(PropertiesParser.Token)
+     * @return {@code this}
+     */
     public Cursor addEol() {
         return add(PropertiesParser.Token.EOL);
     }

From 270ce3be655511a040baa8d61ca0275f8927196d Mon Sep 17 00:00:00 2001
From: "eric.jarosch" <eric.jarosch@nexus-ag.de>
Date: Wed, 23 Sep 2026 18:57:30 +0200
Subject: [PATCH 2/2] rephrase Cursor#add to match java.util.List.add(int, T)

---
 src/main/java/org/codejive/properties/Cursor.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/codejive/properties/Cursor.java b/src/main/java/org/codejive/properties/Cursor.java
index 403e99d..7afd91b 100644
--- a/src/main/java/org/codejive/properties/Cursor.java
+++ b/src/main/java/org/codejive/properties/Cursor.java
@@ -146,9 +146,9 @@ public int prevCount(Predicate<PropertiesParser.Token> accept) {
     }
 
     /**
-     * Inserts a token at the current position, pushing the current token (if any) forwards.
+     * Inserts a token at the current position, shifting the current token (if any) and any subsequent tokens to the right (adds one to their indices).
      * <br/>
-     * This method advances the cursor by one token (causing it to point at the initial token again).
+     * This method advances the cursor by one, such that the cursor state remains unchanged (pointing to the same token as before).
      * @param token the token to insert.
      * @return {@code this}
      */