From 7ab99a4da5c5c397450c14d7ca24f1236059b0ae Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Fri, 1 Aug 2025 22:31:45 +0200 Subject: [PATCH 1/7] add descriptions --- .../ch/njol/skript/registrations/Feature.java | 189 +++++++++++++++++- .../skript/lang/experiment/Experiment.java | 15 ++ 2 files changed, 197 insertions(+), 7 deletions(-) diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index eb2c2f0f9d7..7acd93416c2 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -3,6 +3,7 @@ import ch.njol.skript.SkriptAddon; import ch.njol.skript.patterns.PatternCompiler; import ch.njol.skript.patterns.SkriptPattern; +import org.jetbrains.annotations.NotNull; import org.skriptlang.skript.lang.experiment.Experiment; import org.skriptlang.skript.lang.experiment.ExperimentRegistry; import org.skriptlang.skript.lang.experiment.LifeCycle; @@ -11,13 +12,177 @@ * Experimental feature toggles as provided by Skript itself. */ public enum Feature implements Experiment { - EXAMPLES("examples", LifeCycle.STABLE), - QUEUES("queues", LifeCycle.EXPERIMENTAL), - FOR_EACH_LOOPS("for loop", LifeCycle.EXPERIMENTAL, "for [each] loop[s]"), - SCRIPT_REFLECTION("reflection", LifeCycle.EXPERIMENTAL, "[script] reflection"), - CATCH_ERRORS("catch runtime errors", LifeCycle.EXPERIMENTAL, "error catching [section]"), - TYPE_HINTS("type hints", LifeCycle.EXPERIMENTAL, "[local variable] type hints"), - DAMAGE_SOURCE("damage source", LifeCycle.EXPERIMENTAL, "damage source[s]") + + EXAMPLES("examples", LifeCycle.STABLE) { + @Override + public @NotNull String displayName() { + return "Examples"; + } + + @Override + public @NotNull String description() { + return """ + A section used to provide examples inside code. + """; + } + }, + QUEUES("queues", LifeCycle.EXPERIMENTAL) { + @Override + public @NotNull String displayName() { + return "Queues"; + } + + @Override + public @NotNull String description() { + return """ + A collection that removes elements whenever they are requested. + + This is useful for processing tasks or keeping track of things that need to happen only once. + + ``` + set {queue} to a new queue of "hello" and "world" + + broadcast the first element of {queue} + # "hello" is now removed + + broadcast the first element of {queue} + # "world" is now removed + + # queue is empty + ``` + + ``` + set {queue} to a new queue of all players + + set {player 1} to a random element out of {queue}\s + set {player 2} to a random element out of {queue} + # players 1 and 2 are guaranteed to be distinct + ``` + + Queues can be looped over like a regular list. + """; + } + }, + FOR_EACH_LOOPS("for loop", LifeCycle.EXPERIMENTAL, "for [each] loop[s]") { + @Override + public @NotNull String displayName() { + return "For Loops"; + } + + @Override + public @NotNull String description() { + return """ + A new kind of loop syntax that stores the loop index and value in variables for convenience. + + This can be used to avoid confusion when nesting multiple loops inside each other. + + ``` + for {_index}, {_value} in {my list::*}: + broadcast "%{_index}%: %{_value}%" + ``` + + ``` + for each {_player} in all players: + send "Hello %{_player}%!" to {_player} + ``` + + All existing loop features are also available in this section. + """; + } + }, + SCRIPT_REFLECTION("reflection", LifeCycle.EXPERIMENTAL, "[script] reflection") { + @Override + public @NotNull String displayName() { + return "Script Reflection"; + } + + @Override + public @NotNull String description() { + return """ + This feature includes: + + - The ability to reference a script in code. + - Finding and running functions by name. + - Reading configuration files and values. + """; + } + }, + CATCH_ERRORS("catch runtime errors", LifeCycle.EXPERIMENTAL, "error catching [section]") { + @Override + public @NotNull String displayName() { + return "Runtime Error Catching"; + } + + @Override + public @NotNull String description() { + return """ + A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. + + ``` + catch runtime errors: + ... + set worldborder center of {_border} to {_my unsafe location} + ... + if last caught runtime errors contains "Your location can't have a NaN value as one of its components": + set worldborder center of {_border} to location(0, 0, 0) + ``` + """; + } + }, + TYPE_HINTS("type hints", LifeCycle.EXPERIMENTAL, "[local variable] type hints") { + @Override + public @NotNull String displayName() { + return "Type Hints"; + } + + @Override + public @NotNull String description() { + return """ + Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: + + ``` + set {_a} to 5 + set {_b} to "some string" + ... do stuff ... + set {_c} to {_a} in lowercase # oops i used the wrong variable + ``` + + Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. + + Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: + + ``` + {_var} # can use type hints + {_var::%player's name%} # can't use type hints + ``` + """; + } + }, + DAMAGE_SOURCE("damage source", LifeCycle.EXPERIMENTAL, "damage source[s]") { + @Override + public @NotNull String displayName() { + return "Damage Sources"; + } + + @Override + public @NotNull String description() { + return """ + Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. + + Below is an example of what damaging using custom damage sources looks like: + + ``` + damage all players by 5 using a custom damage source: + set the damage type to magic + set the causing entity to {_player} + set the direct entity to {_arrow} + set the damage location to location(0, 0, 10) + ``` + + For more details about the syntax, visit damage source on our documentation website. + """; + } + } ; private final String codeName; @@ -40,6 +205,16 @@ public static void registerAll(SkriptAddon addon, ExperimentRegistry manager) { } } + @Override + public @NotNull String displayName() { + return ""; + } + + @Override + public @NotNull String description() { + return ""; + } + @Override public String codeName() { return codeName; diff --git a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java index 55422718eb7..fa44ecd0e3b 100644 --- a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java +++ b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java @@ -4,6 +4,7 @@ import ch.njol.skript.patterns.SkriptPattern; import ch.njol.skript.registrations.Feature; import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.NotNull; import java.util.Objects; @@ -56,6 +57,20 @@ default boolean isKnown() { */ SkriptPattern pattern(); + /** + * @return The display name for this experiment. + */ + default @NotNull String displayName() { + return ""; + } + + /** + * @return The description for this experiment. + */ + default @NotNull String description() { + return ""; + } + /** * @return Whether the usage pattern of this experiment matches the input text */ From 8f428a1e59762acba92e355a369304aca80c8dec Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Fri, 1 Aug 2025 23:02:17 +0200 Subject: [PATCH 2/7] add experiments to docs.json --- .../ch/njol/skript/doc/JSONGenerator.java | 42 +++++++++++++++++++ .../njol/skript/test/runner/TestFeatures.java | 4 +- 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index d30d0f039ac..3c5c66c0519 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -18,6 +18,7 @@ import org.bukkit.event.block.BlockCanBuildEvent; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +import org.skriptlang.skript.lang.experiment.Experiment; import org.skriptlang.skript.lang.structure.Structure; import org.skriptlang.skript.lang.structure.StructureInfo; @@ -366,6 +367,45 @@ private static JsonArray generateFunctionArray(Iterator> functio return syntaxArray; } + /** + * Generates a JsonArray with all data for each {@link Experiment}. + * + * @return a JsonArray containing the documentation JsonObjects for each experiment + */ + private static JsonArray generateExperiments() { + JsonArray array = new JsonArray(); + + for (Experiment experiment : Skript.experiments().registered()) { + JsonObject object = new JsonObject(); + + object.addProperty("id", experiment.codeName()); + + if (experiment.displayName().isEmpty()) { + object.addProperty("name", (String) null); + } else { + object.addProperty("name", experiment.displayName()); + } + + JsonArray description = new JsonArray(); + for (String part : experiment.description().split("\\n")) { + description.add(part); + } + + if (experiment.description().isEmpty()) { + object.add("description", null); + } else { + object.add("description", description); + } + + object.addProperty("pattern", experiment.pattern().toString()); + object.addProperty("phase", experiment.phase().name().toLowerCase(Locale.ENGLISH)); + + array.add(object); + } + + return array; + } + /** * Cleans the provided patterns * @@ -416,6 +456,8 @@ public void generate() { jsonDocs.add("functions", generateFunctionArray(Functions.getJavaFunctions().iterator())); + jsonDocs.add("experiments", generateExperiments()); + saveDocs(outputDir.toPath().resolve("docs.json"), jsonDocs); } diff --git a/src/main/java/ch/njol/skript/test/runner/TestFeatures.java b/src/main/java/ch/njol/skript/test/runner/TestFeatures.java index e42fcdb5d81..6ff1a9d58e1 100644 --- a/src/main/java/ch/njol/skript/test/runner/TestFeatures.java +++ b/src/main/java/ch/njol/skript/test/runner/TestFeatures.java @@ -63,7 +63,9 @@ public SkriptPattern pattern() { } static { - registerAll(Skript.getAddonInstance(), Skript.experiments()); + if (!TestMode.GEN_DOCS) { + registerAll(Skript.getAddonInstance(), Skript.experiments()); + } } } From 0a0480213dee7ed32077b4b75104b97efc4b6dea Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:39:05 +0200 Subject: [PATCH 3/7] move to constructor --- .../ch/njol/skript/registrations/Feature.java | 317 ++++++++---------- 1 file changed, 144 insertions(+), 173 deletions(-) diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index 7acd93416c2..1937e31a466 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -3,6 +3,7 @@ import ch.njol.skript.SkriptAddon; import ch.njol.skript.patterns.PatternCompiler; import ch.njol.skript.patterns.SkriptPattern; +import com.google.common.base.Preconditions; import org.jetbrains.annotations.NotNull; import org.skriptlang.skript.lang.experiment.Experiment; import org.skriptlang.skript.lang.experiment.ExperimentRegistry; @@ -13,183 +14,153 @@ */ public enum Feature implements Experiment { - EXAMPLES("examples", LifeCycle.STABLE) { - @Override - public @NotNull String displayName() { - return "Examples"; - } - - @Override - public @NotNull String description() { - return """ - A section used to provide examples inside code. - """; - } - }, - QUEUES("queues", LifeCycle.EXPERIMENTAL) { - @Override - public @NotNull String displayName() { - return "Queues"; - } - - @Override - public @NotNull String description() { - return """ - A collection that removes elements whenever they are requested. - - This is useful for processing tasks or keeping track of things that need to happen only once. - - ``` - set {queue} to a new queue of "hello" and "world" - - broadcast the first element of {queue} - # "hello" is now removed - - broadcast the first element of {queue} - # "world" is now removed - - # queue is empty - ``` - - ``` - set {queue} to a new queue of all players - - set {player 1} to a random element out of {queue}\s - set {player 2} to a random element out of {queue} - # players 1 and 2 are guaranteed to be distinct - ``` - - Queues can be looped over like a regular list. - """; - } - }, - FOR_EACH_LOOPS("for loop", LifeCycle.EXPERIMENTAL, "for [each] loop[s]") { - @Override - public @NotNull String displayName() { - return "For Loops"; - } - - @Override - public @NotNull String description() { - return """ - A new kind of loop syntax that stores the loop index and value in variables for convenience. - - This can be used to avoid confusion when nesting multiple loops inside each other. - - ``` - for {_index}, {_value} in {my list::*}: - broadcast "%{_index}%: %{_value}%" - ``` - - ``` - for each {_player} in all players: - send "Hello %{_player}%!" to {_player} - ``` - - All existing loop features are also available in this section. - """; - } - }, - SCRIPT_REFLECTION("reflection", LifeCycle.EXPERIMENTAL, "[script] reflection") { - @Override - public @NotNull String displayName() { - return "Script Reflection"; - } - - @Override - public @NotNull String description() { - return """ - This feature includes: - - - The ability to reference a script in code. - - Finding and running functions by name. - - Reading configuration files and values. - """; - } - }, - CATCH_ERRORS("catch runtime errors", LifeCycle.EXPERIMENTAL, "error catching [section]") { - @Override - public @NotNull String displayName() { - return "Runtime Error Catching"; - } - - @Override - public @NotNull String description() { - return """ - A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. - - ``` - catch runtime errors: - ... - set worldborder center of {_border} to {_my unsafe location} - ... - if last caught runtime errors contains "Your location can't have a NaN value as one of its components": - set worldborder center of {_border} to location(0, 0, 0) - ``` - """; - } - }, - TYPE_HINTS("type hints", LifeCycle.EXPERIMENTAL, "[local variable] type hints") { - @Override - public @NotNull String displayName() { - return "Type Hints"; - } - - @Override - public @NotNull String description() { - return """ - Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: - - ``` - set {_a} to 5 - set {_b} to "some string" - ... do stuff ... - set {_c} to {_a} in lowercase # oops i used the wrong variable - ``` - - Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. - - Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: - - ``` - {_var} # can use type hints - {_var::%player's name%} # can't use type hints - ``` - """; - } - }, - DAMAGE_SOURCE("damage source", LifeCycle.EXPERIMENTAL, "damage source[s]") { - @Override - public @NotNull String displayName() { - return "Damage Sources"; - } - - @Override - public @NotNull String description() { - return """ - Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. - - Below is an example of what damaging using custom damage sources looks like: - - ``` - damage all players by 5 using a custom damage source: - set the damage type to magic - set the causing entity to {_player} - set the direct entity to {_arrow} - set the damage location to location(0, 0, 10) - ``` - - For more details about the syntax, visit damage source on our documentation website. - """; - } - } + EXAMPLES("Examples", + """ + A section used to provide examples inside code. + + ``` + example: + kick the player due to "you are not allowed here!" + ``` + """, + "examples", + LifeCycle.STABLE), + QUEUES("Queues", + """ + A collection that removes elements whenever they are requested. + + This is useful for processing tasks or keeping track of things that need to happen only once. + + ``` + set {queue} to a new queue of "hello" and "world" + + broadcast the first element of {queue} + # "hello" is now removed + + broadcast the first element of {queue} + # "world" is now removed + + # queue is empty + ``` + + ``` + set {queue} to a new queue of all players + + set {player 1} to a random element out of {queue}\s + set {player 2} to a random element out of {queue} + # players 1 and 2 are guaranteed to be distinct + ``` + + Queues can be looped over like a regular list. + """, + "queues", + LifeCycle.EXPERIMENTAL), + FOR_EACH_LOOPS("For Loops", + """ + A new kind of loop syntax that stores the loop index and value in variables for convenience. + + This can be used to avoid confusion when nesting multiple loops inside each other. + + ``` + for {_index}, {_value} in {my list::*}: + broadcast "%{_index}%: %{_value}%" + ``` + + ``` + for each {_player} in all players: + send "Hello %{_player}%!" to {_player} + ``` + + All existing loop features are also available in this section. + """, + "for loop", + LifeCycle.EXPERIMENTAL, + "for [each] loop[s]"), + SCRIPT_REFLECTION("Script Reflection", + """ + This feature includes: + + - The ability to reference a script in code. + - Finding and running functions by name. + - Reading configuration files and values. + """, "reflection", + LifeCycle.EXPERIMENTAL, + "[script] reflection"), + CATCH_ERRORS("Runtime Error Catching", + """ + A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. + + ``` + catch runtime errors: + ... + set worldborder center of {_border} to {_my unsafe location} + ... + if last caught runtime errors contains "Your location can't have a NaN value as one of its components": + set worldborder center of {_border} to location(0, 0, 0) + ``` + """, + "catch runtime errors", + LifeCycle.EXPERIMENTAL, + "error catching [section]"), + TYPE_HINTS("Type Hints", + """ + Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: + + ``` + set {_a} to 5 + set {_b} to "some string" + ... do stuff ... + set {_c} to {_a} in lowercase # oops i used the wrong variable + ``` + + Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. + + Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: + + ``` + {_var} # can use type hints + {_var::%player's name%} # can't use type hints + ``` + """, + "type hints", + LifeCycle.EXPERIMENTAL, + "[local variable] type hints"), + DAMAGE_SOURCE("Damage Sources", + """ + Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. + + Below is an example of what damaging using custom damage sources looks like: + + ``` + damage all players by 5 using a custom damage source: + set the damage type to magic + set the causing entity to {_player} + set the direct entity to {_arrow} + set the damage location to location(0, 0, 10) + ``` + + For more details about the syntax, visit damage source on our documentation website. + """, + "damage source", + LifeCycle.EXPERIMENTAL, + "damage source[s]") ; private final String codeName; + private final String displayName; + private final String description; private final LifeCycle phase; private final SkriptPattern compiledPattern; - Feature(String codeName, LifeCycle phase, String... patterns) { + Feature(@NotNull String displayName, @NotNull String description, + @NotNull String codeName, @NotNull LifeCycle phase, + String... patterns) { + Preconditions.checkNotNull(codeName, "codeName cannot be null"); + Preconditions.checkNotNull(displayName, "displayName cannot be null"); + Preconditions.checkNotNull(description, "description cannot be null"); + + this.displayName = displayName; + this.description = description; this.codeName = codeName; this.phase = phase; this.compiledPattern = switch (patterns.length) { @@ -207,12 +178,12 @@ public static void registerAll(SkriptAddon addon, ExperimentRegistry manager) { @Override public @NotNull String displayName() { - return ""; + return displayName; } @Override public @NotNull String description() { - return ""; + return description; } @Override From 3f76e0ba58b33dbfd2ebc6bd1777682d6a5b4a69 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Wed, 20 Aug 2025 20:29:28 +0200 Subject: [PATCH 4/7] requested changes --- .../ch/njol/skript/registrations/Feature.java | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index 1937e31a466..c8282f0142d 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -15,7 +15,8 @@ public enum Feature implements Experiment { EXAMPLES("Examples", - """ + "examples", + """ A section used to provide examples inside code. ``` @@ -23,10 +24,10 @@ public enum Feature implements Experiment { kick the player due to "you are not allowed here!" ``` """, - "examples", - LifeCycle.STABLE), + LifeCycle.STABLE), QUEUES("Queues", - """ + "queues", + """ A collection that removes elements whenever they are requested. This is useful for processing tasks or keeping track of things that need to happen only once. @@ -53,57 +54,58 @@ public enum Feature implements Experiment { Queues can be looped over like a regular list. """, - "queues", - LifeCycle.EXPERIMENTAL), + LifeCycle.EXPERIMENTAL), FOR_EACH_LOOPS("For Loops", - """ + "for loop", + """ A new kind of loop syntax that stores the loop index and value in variables for convenience. This can be used to avoid confusion when nesting multiple loops inside each other. ``` for {_index}, {_value} in {my list::*}: - broadcast "%{_index}%: %{_value}%" + broadcast "%{_index}%: %{_value}%" ``` ``` for each {_player} in all players: - send "Hello %{_player}%!" to {_player} + send "Hello %{_player}%!" to {_player} ``` All existing loop features are also available in this section. """, - "for loop", - LifeCycle.EXPERIMENTAL, - "for [each] loop[s]"), + LifeCycle.EXPERIMENTAL, + "for [each] loop[s]"), SCRIPT_REFLECTION("Script Reflection", - """ + "reflection", + """ This feature includes: - The ability to reference a script in code. - Finding and running functions by name. - Reading configuration files and values. - """, "reflection", - LifeCycle.EXPERIMENTAL, - "[script] reflection"), + """, + LifeCycle.EXPERIMENTAL, + "[script] reflection"), CATCH_ERRORS("Runtime Error Catching", - """ + "catch runtime errors", + """ A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. ``` catch runtime errors: - ... - set worldborder center of {_border} to {_my unsafe location} - ... + ... + set worldborder center of {_border} to {_my unsafe location} + ... if last caught runtime errors contains "Your location can't have a NaN value as one of its components": - set worldborder center of {_border} to location(0, 0, 0) + set worldborder center of {_border} to location(0, 0, 0) ``` """, - "catch runtime errors", - LifeCycle.EXPERIMENTAL, - "error catching [section]"), + LifeCycle.EXPERIMENTAL, + "error catching [section]"), TYPE_HINTS("Type Hints", - """ + "type hints", + """ Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: ``` @@ -122,11 +124,11 @@ public enum Feature implements Experiment { {_var::%player's name%} # can't use type hints ``` """, - "type hints", - LifeCycle.EXPERIMENTAL, - "[local variable] type hints"), + LifeCycle.EXPERIMENTAL, + "[local variable] type hints"), DAMAGE_SOURCE("Damage Sources", - """ + "damage source", + """ Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. Below is an example of what damaging using custom damage sources looks like: @@ -141,19 +143,17 @@ set the damage location to location(0, 0, 10) For more details about the syntax, visit damage source on our documentation website. """, - "damage source", - LifeCycle.EXPERIMENTAL, - "damage source[s]") - ; + LifeCycle.EXPERIMENTAL, + "damage source[s]"); - private final String codeName; private final String displayName; + private final String codeName; private final String description; private final LifeCycle phase; private final SkriptPattern compiledPattern; - Feature(@NotNull String displayName, @NotNull String description, - @NotNull String codeName, @NotNull LifeCycle phase, + Feature(@NotNull String displayName, @NotNull String codeName, + @NotNull String description, @NotNull LifeCycle phase, String... patterns) { Preconditions.checkNotNull(codeName, "codeName cannot be null"); Preconditions.checkNotNull(displayName, "displayName cannot be null"); From bcf1584d1895bc3567ffd25aab96eb6bb253954c Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Thu, 21 Aug 2025 15:24:59 +0200 Subject: [PATCH 5/7] requested changes --- .../ch/njol/skript/registrations/Feature.java | 30 +++++++++---------- .../skript/lang/experiment/Experiment.java | 2 +- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index c8282f0142d..6d9084b5e2b 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -15,8 +15,8 @@ public enum Feature implements Experiment { EXAMPLES("Examples", - "examples", - """ + "examples", + """ A section used to provide examples inside code. ``` @@ -26,8 +26,8 @@ public enum Feature implements Experiment { """, LifeCycle.STABLE), QUEUES("Queues", - "queues", - """ + "queues", + """ A collection that removes elements whenever they are requested. This is useful for processing tasks or keeping track of things that need to happen only once. @@ -56,8 +56,8 @@ public enum Feature implements Experiment { """, LifeCycle.EXPERIMENTAL), FOR_EACH_LOOPS("For Loops", - "for loop", - """ + "for loop", + """ A new kind of loop syntax that stores the loop index and value in variables for convenience. This can be used to avoid confusion when nesting multiple loops inside each other. @@ -77,8 +77,8 @@ public enum Feature implements Experiment { LifeCycle.EXPERIMENTAL, "for [each] loop[s]"), SCRIPT_REFLECTION("Script Reflection", - "reflection", - """ + "reflection", + """ This feature includes: - The ability to reference a script in code. @@ -88,8 +88,8 @@ public enum Feature implements Experiment { LifeCycle.EXPERIMENTAL, "[script] reflection"), CATCH_ERRORS("Runtime Error Catching", - "catch runtime errors", - """ + "catch runtime errors", + """ A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. ``` @@ -104,8 +104,8 @@ public enum Feature implements Experiment { LifeCycle.EXPERIMENTAL, "error catching [section]"), TYPE_HINTS("Type Hints", - "type hints", - """ + "type hints", + """ Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: ``` @@ -127,8 +127,8 @@ public enum Feature implements Experiment { LifeCycle.EXPERIMENTAL, "[local variable] type hints"), DAMAGE_SOURCE("Damage Sources", - "damage source", - """ + "damage source", + """ Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. Below is an example of what damaging using custom damage sources looks like: @@ -160,7 +160,7 @@ set the damage location to location(0, 0, 10) Preconditions.checkNotNull(description, "description cannot be null"); this.displayName = displayName; - this.description = description; + this.description = description.strip(); this.codeName = codeName; this.phase = phase; this.compiledPattern = switch (patterns.length) { diff --git a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java index fa44ecd0e3b..523ca85e8fa 100644 --- a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java +++ b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java @@ -61,7 +61,7 @@ default boolean isKnown() { * @return The display name for this experiment. */ default @NotNull String displayName() { - return ""; + return codeName(); } /** From 99e473044a3e4859cc90ccc78a5fb90fa19111e7 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Thu, 21 Aug 2025 21:15:50 +0200 Subject: [PATCH 6/7] format !! --- .../ch/njol/skript/registrations/Feature.java | 220 +++++++++--------- 1 file changed, 110 insertions(+), 110 deletions(-) diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index 6d9084b5e2b..63c7e9c0d93 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -17,134 +17,134 @@ public enum Feature implements Experiment { EXAMPLES("Examples", "examples", """ - A section used to provide examples inside code. - - ``` - example: - kick the player due to "you are not allowed here!" - ``` - """, - LifeCycle.STABLE), + A section used to provide examples inside code. + + ``` + example: + kick the player due to "you are not allowed here!" + ``` + """, + LifeCycle.STABLE), QUEUES("Queues", "queues", """ - A collection that removes elements whenever they are requested. - - This is useful for processing tasks or keeping track of things that need to happen only once. - - ``` - set {queue} to a new queue of "hello" and "world" - - broadcast the first element of {queue} - # "hello" is now removed - - broadcast the first element of {queue} - # "world" is now removed - - # queue is empty - ``` - - ``` - set {queue} to a new queue of all players - - set {player 1} to a random element out of {queue}\s - set {player 2} to a random element out of {queue} - # players 1 and 2 are guaranteed to be distinct - ``` - - Queues can be looped over like a regular list. - """, - LifeCycle.EXPERIMENTAL), + A collection that removes elements whenever they are requested. + + This is useful for processing tasks or keeping track of things that need to happen only once. + + ``` + set {queue} to a new queue of "hello" and "world" + + broadcast the first element of {queue} + # "hello" is now removed + + broadcast the first element of {queue} + # "world" is now removed + + # queue is empty + ``` + + ``` + set {queue} to a new queue of all players + + set {player 1} to a random element out of {queue}\s + set {player 2} to a random element out of {queue} + # players 1 and 2 are guaranteed to be distinct + ``` + + Queues can be looped over like a regular list. + """, + LifeCycle.EXPERIMENTAL), FOR_EACH_LOOPS("For Loops", "for loop", """ - A new kind of loop syntax that stores the loop index and value in variables for convenience. - - This can be used to avoid confusion when nesting multiple loops inside each other. - - ``` - for {_index}, {_value} in {my list::*}: - broadcast "%{_index}%: %{_value}%" - ``` - - ``` - for each {_player} in all players: - send "Hello %{_player}%!" to {_player} - ``` - - All existing loop features are also available in this section. - """, - LifeCycle.EXPERIMENTAL, - "for [each] loop[s]"), + A new kind of loop syntax that stores the loop index and value in variables for convenience. + + This can be used to avoid confusion when nesting multiple loops inside each other. + + ``` + for {_index}, {_value} in {my list::*}: + broadcast "%{_index}%: %{_value}%" + ``` + + ``` + for each {_player} in all players: + send "Hello %{_player}%!" to {_player} + ``` + + All existing loop features are also available in this section. + """, + LifeCycle.EXPERIMENTAL, + "for [each] loop[s]"), SCRIPT_REFLECTION("Script Reflection", "reflection", """ - This feature includes: - - - The ability to reference a script in code. - - Finding and running functions by name. - - Reading configuration files and values. - """, - LifeCycle.EXPERIMENTAL, - "[script] reflection"), + This feature includes: + + - The ability to reference a script in code. + - Finding and running functions by name. + - Reading configuration files and values. + """, + LifeCycle.EXPERIMENTAL, + "[script] reflection"), CATCH_ERRORS("Runtime Error Catching", "catch runtime errors", """ - A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. - - ``` - catch runtime errors: - ... - set worldborder center of {_border} to {_my unsafe location} - ... - if last caught runtime errors contains "Your location can't have a NaN value as one of its components": - set worldborder center of {_border} to location(0, 0, 0) - ``` - """, - LifeCycle.EXPERIMENTAL, - "error catching [section]"), + A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. + + ``` + catch runtime errors: + ... + set worldborder center of {_border} to {_my unsafe location} + ... + if last caught runtime errors contains "Your location can't have a NaN value as one of its components": + set worldborder center of {_border} to location(0, 0, 0) + ``` + """, + LifeCycle.EXPERIMENTAL, + "error catching [section]"), TYPE_HINTS("Type Hints", "type hints", """ - Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: - - ``` - set {_a} to 5 - set {_b} to "some string" - ... do stuff ... - set {_c} to {_a} in lowercase # oops i used the wrong variable - ``` - - Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. - - Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: - - ``` - {_var} # can use type hints - {_var::%player's name%} # can't use type hints - ``` - """, - LifeCycle.EXPERIMENTAL, - "[local variable] type hints"), + Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: + + ``` + set {_a} to 5 + set {_b} to "some string" + ... do stuff ... + set {_c} to {_a} in lowercase # oops i used the wrong variable + ``` + + Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. + + Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: + + ``` + {_var} # can use type hints + {_var::%player's name%} # can't use type hints + ``` + """, + LifeCycle.EXPERIMENTAL, + "[local variable] type hints"), DAMAGE_SOURCE("Damage Sources", "damage source", """ - Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. - - Below is an example of what damaging using custom damage sources looks like: - - ``` - damage all players by 5 using a custom damage source: - set the damage type to magic - set the causing entity to {_player} - set the direct entity to {_arrow} - set the damage location to location(0, 0, 10) - ``` - - For more details about the syntax, visit damage source on our documentation website. - """, - LifeCycle.EXPERIMENTAL, - "damage source[s]"); + Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. + + Below is an example of what damaging using custom damage sources looks like: + + ``` + damage all players by 5 using a custom damage source: + set the damage type to magic + set the causing entity to {_player} + set the direct entity to {_arrow} + set the damage location to location(0, 0, 10) + ``` + + For more details about the syntax, visit damage source on our documentation website. + """, + LifeCycle.EXPERIMENTAL, + "damage source[s]"); private final String displayName; private final String codeName; From edf03636314e056548c9ddf48be0a6594a421ace Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Fri, 29 Aug 2025 21:39:04 +0200 Subject: [PATCH 7/7] requested changes --- .../ch/njol/skript/doc/JSONGenerator.java | 9 ++- .../ch/njol/skript/registrations/Feature.java | 58 ++++++++++++------- .../skript/lang/experiment/Experiment.java | 6 +- 3 files changed, 44 insertions(+), 29 deletions(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index 3c5c66c0519..194f17a6be9 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -386,14 +386,13 @@ private static JsonArray generateExperiments() { object.addProperty("name", experiment.displayName()); } - JsonArray description = new JsonArray(); - for (String part : experiment.description().split("\\n")) { - description.add(part); - } - if (experiment.description().isEmpty()) { object.add("description", null); } else { + JsonArray description = new JsonArray(); + for (String part : experiment.description()) { + description.add(part); + } object.add("description", description); } diff --git a/src/main/java/ch/njol/skript/registrations/Feature.java b/src/main/java/ch/njol/skript/registrations/Feature.java index 63c7e9c0d93..130866acc4b 100644 --- a/src/main/java/ch/njol/skript/registrations/Feature.java +++ b/src/main/java/ch/njol/skript/registrations/Feature.java @@ -9,13 +9,16 @@ import org.skriptlang.skript.lang.experiment.ExperimentRegistry; import org.skriptlang.skript.lang.experiment.LifeCycle; +import java.util.Collection; +import java.util.List; + /** * Experimental feature toggles as provided by Skript itself. */ public enum Feature implements Experiment { - EXAMPLES("Examples", - "examples", + EXAMPLES("examples", + "Examples", """ A section used to provide examples inside code. @@ -25,8 +28,8 @@ public enum Feature implements Experiment { ``` """, LifeCycle.STABLE), - QUEUES("Queues", - "queues", + QUEUES("queues", + "Queues", """ A collection that removes elements whenever they are requested. @@ -55,8 +58,8 @@ public enum Feature implements Experiment { Queues can be looped over like a regular list. """, LifeCycle.EXPERIMENTAL), - FOR_EACH_LOOPS("For Loops", - "for loop", + FOR_EACH_LOOPS("for loop", + "For Loops", """ A new kind of loop syntax that stores the loop index and value in variables for convenience. @@ -76,8 +79,8 @@ public enum Feature implements Experiment { """, LifeCycle.EXPERIMENTAL, "for [each] loop[s]"), - SCRIPT_REFLECTION("Script Reflection", - "reflection", + SCRIPT_REFLECTION("reflection", + "Script Reflection", """ This feature includes: @@ -87,10 +90,12 @@ public enum Feature implements Experiment { """, LifeCycle.EXPERIMENTAL, "[script] reflection"), - CATCH_ERRORS("Runtime Error Catching", - "catch runtime errors", + CATCH_ERRORS("catch runtime errors", + "Runtime Error Catching", """ - A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors. + A new catch runtime errors section allows you to catch and \ + suppress runtime errors within it and access them later with \ + the last caught runtime errors. ``` catch runtime errors: @@ -103,10 +108,12 @@ public enum Feature implements Experiment { """, LifeCycle.EXPERIMENTAL, "error catching [section]"), - TYPE_HINTS("Type Hints", - "type hints", + TYPE_HINTS("type hints", + "Type Hints", """ - Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: + Local variable type hints enable Skript to understand \ + what kind of values your local variables will hold at parse time. \ + Consider the following example: ``` set {_a} to 5 @@ -115,9 +122,13 @@ public enum Feature implements Experiment { set {_c} to {_a} in lowercase # oops i used the wrong variable ``` - Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. + Previously, the code above would parse without issue. \ + However, Skript now understands that when it is used, \ + {_a} could only be a number (and not a text). \ + Thus, the code above would now error with a message about mismatched types. - Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions: + Please note that this feature is currently only supported by simple local variables. \ + A simple local variable is one whose name does not contain any expressions: ``` {_var} # can use type hints @@ -126,10 +137,13 @@ public enum Feature implements Experiment { """, LifeCycle.EXPERIMENTAL, "[local variable] type hints"), - DAMAGE_SOURCE("Damage Sources", - "damage source", + DAMAGE_SOURCE("damage source", + "Damage Sources", """ - Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. + Damage sources are a more advanced and detailed version of damage causes. \ + Damage sources include information such as the type of damage, \ + the location where the damage originated from, the entity that \ + directly caused the damage, and more. Below is an example of what damaging using custom damage sources looks like: @@ -152,7 +166,7 @@ set the damage location to location(0, 0, 10) private final LifeCycle phase; private final SkriptPattern compiledPattern; - Feature(@NotNull String displayName, @NotNull String codeName, + Feature(@NotNull String codeName, @NotNull String displayName, @NotNull String description, @NotNull LifeCycle phase, String... patterns) { Preconditions.checkNotNull(codeName, "codeName cannot be null"); @@ -182,8 +196,8 @@ public static void registerAll(SkriptAddon addon, ExperimentRegistry manager) { } @Override - public @NotNull String description() { - return description; + public @NotNull Collection description() { + return List.of(description); } @Override diff --git a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java index 523ca85e8fa..95cb20964dc 100644 --- a/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java +++ b/src/main/java/org/skriptlang/skript/lang/experiment/Experiment.java @@ -6,6 +6,8 @@ import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.NotNull; +import java.util.Collection; +import java.util.List; import java.util.Objects; /** @@ -67,8 +69,8 @@ default boolean isKnown() { /** * @return The description for this experiment. */ - default @NotNull String description() { - return ""; + default @NotNull Collection description() { + return List.of(); } /**