From 50fde7d4cd42cc839582247363fef9655bac1331 Mon Sep 17 00:00:00 2001
From: Patrick Miller <apickledwalrus@icloud.com>
Date: Thu, 30 Jul 2026 12:18:44 -0400
Subject: [PATCH] Improve EntryValidator javadocs

---
 .../skript/lang/entry/EntryValidator.java     | 40 +++++++++----------
 1 file changed, 18 insertions(+), 22 deletions(-)

diff --git a/src/main/java/org/skriptlang/skript/lang/entry/EntryValidator.java b/src/main/java/org/skriptlang/skript/lang/entry/EntryValidator.java
index 978205a33b7..391432d1bc4 100644
--- a/src/main/java/org/skriptlang/skript/lang/entry/EntryValidator.java
+++ b/src/main/java/org/skriptlang/skript/lang/entry/EntryValidator.java
@@ -61,7 +61,8 @@ public List<EntryData<?>> getEntryData() {
 	}
 
 	/**
-	 * @return A predicate that tests whether a node should be allowed.
+	 * @return A predicate that tests whether a node not explicitly handled by any {@link #getEntryData()}
+	 *  should be allowed to be present.
 	 */
 	public @Nullable Predicate<Node> getUnexpectedNodeTester() {
 		return unexpectedNodeTester;
@@ -86,10 +87,8 @@ public Function<String, String> getMissingRequiredEntryMessage() {
 	/**
 	 * Validates a node using this entry validator.
 	 * @param sectionNode The node to validate.
-	 * @return A pair containing a map of handled nodes and a list of unhandled nodes
-	 *         (if this validator permits unhandled nodes)
-	 *         The returned map uses the matched entry data's key as a key and
-	 *         uses a pair containing the entry data and matching node
+	 * @return An entry container holding the validated nodes
+	 * 	        along with any additional nodes (if permitted by {@link #getUnexpectedNodeTester()}).
 	 *         Will return null if the provided node couldn't be validated.
 	 */
 	public @Nullable EntryContainer validate(SectionNode sectionNode) {
@@ -108,7 +107,7 @@ public Function<String, String> getMissingRequiredEntryMessage() {
 				EntryData<?> data = iterator.next();
 				if (data.canCreateWith(node)) { // Determine if it's a match
 					Collection<Node> nodes = handledNodes.computeIfAbsent(
-						data.getKey(), k -> new LinkedList<>()
+						data.getKey(), ignored -> new LinkedList<>()
 					);
 					nodes.add(node);
 					// we do not expect this entry data anymore
@@ -148,7 +147,7 @@ public Function<String, String> getMissingRequiredEntryMessage() {
 
 	/**
 	 * A utility builder for creating an entry validator that can be used to parse
-	 * and validate a {@link SectionNode}.
+	 *  and validate a {@link SectionNode}.
 	 * @see EntryValidator#builder()
 	 */
 	public static class EntryValidatorBuilder {
@@ -188,9 +187,9 @@ protected String getEntrySeparator() {
 		}
 
 		/**
-		 * Updates the separator to be used when creating KeyValue entries. Please note
-		 * that this will not update the separator for already registered KeyValue entries.
-		 * @param separator The new separator for KeyValue entries.
+		 * Updates the separator to be used when creating key/value entries.
+		 * Please note that this will not update the separator for already registered key/value entries.
+		 * @param separator The new separator for key/value entries.
 		 * @return The builder instance.
 		 */
 		public EntryValidatorBuilder entrySeparator(String separator) {
@@ -199,9 +198,9 @@ public EntryValidatorBuilder entrySeparator(String separator) {
 		}
 
 		/**
-		 * A predicate to be supplied for checking whether a Node should be allowed
-		 *  even as an entry not declared in the entry data map.
-		 * The default behavior is that the predicate returns true for every Node tested.
+		 * A predicate to be supplied for checking whether a node not explicitly handled by any {@link #getEntryData()}
+		 *  should cause an error (not be permitted).
+		 * The default behavior is that the predicate returns true for every node tested (i.e., no unknown nodes are permitted).
 		 * @param unexpectedNodeTester The predicate to use.
 		 * @return The builder instance.
 		 */
@@ -211,9 +210,8 @@ public EntryValidatorBuilder unexpectedNodeTester(Predicate<Node> unexpectedNode
 		}
 
 		/**
-		 * A function to be applied when an unexpected Node is encountered during validation.
-		 * A String representing the user input (the Node's key) goes in,
-		 *  and an error message to output comes out.
+		 * A function to create an error message from an unexpected node's key when an unexpected node is encountered during validation
+		 *  (i.e., the node is not allowed by {@link #unexpectedNodeTester}).
 		 * @param unexpectedEntryMessage The function to use.
 		 * @return The builder instance.
 		 */
@@ -223,9 +221,7 @@ public EntryValidatorBuilder unexpectedEntryMessage(Function<String, String> une
 		}
 
 		/**
-		 * A function to be applied when a required Node is missing during validation.
-		 * A String representing the key of the missing entry goes in,
-		 *  and an error message to output comes out.
+		 * A function to create an error message from an expected node's key when that node is missing during validation.
 		 * @param message The function to use.
 		 * @return The builder instance.
 		 */
@@ -235,7 +231,7 @@ public EntryValidatorBuilder missingRequiredEntryMessage(Function<String, String
 		}
 
 		/**
-		 * Adds a new {@link KeyValueEntryData} to this validator that returns the raw, unhandled String value.
+		 * Adds a new {@link KeyValueEntryData} to this validator that returns the raw, unhandled string value.
 		 * The added entry is optional and will use the provided default value as a backup.
 		 * The entry data can be included only once within a single entry container.
 		 * @param key The key of the entry.
@@ -248,7 +244,7 @@ public EntryValidatorBuilder addEntry(String key, @Nullable String defaultValue,
 		}
 
 		/**
-		 * Adds a new {@link KeyValueEntryData} to this validator that returns the raw, unhandled String value.
+		 * Adds a new {@link KeyValueEntryData} to this validator that returns the raw, unhandled string value.
 		 * The added entry is optional and will use the provided default value as a backup.
 		 * @param key The key of the entry.
 		 * @param defaultValue The default value of this entry to use if the user does not include this entry.
@@ -299,7 +295,7 @@ public EntryValidatorBuilder addSection(String key, boolean optional, boolean mu
 		/**
 		 * A method to add custom {@link EntryData} to a validator.
 		 * Custom entry data should be preferred when the default methods included in
-		 * this builder are not expansive enough.
+		 *  this builder are not expansive enough.
 		 * Please note that for custom {@link KeyValueEntryData} implementations, the default entry separator
 		 *  value of this builder will not be used. Instead, {@link #DEFAULT_ENTRY_SEPARATOR} will be used.
 		 * @param entryData The custom entry data to include in this validator.