Skip to content

Improve EntryValidator javadocs #8803

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
APickledWalrus wants to merge 1 commit into
base: dev/patch
Choose a base branch
from
+18 −22
Open

Improve EntryValidator javadocs #8803

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 18 additions & 22 deletions src/main/java/org/skriptlang/skript/lang/entry/EntryValidator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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) {
Expand All @@ -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
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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) {
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
Loading