From d3006fc4b5773205e0a97d62115ddec45a84fb64 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Wed, 6 Aug 2025 17:52:03 +0200 Subject: [PATCH 01/13] init commit --- .../java/ch/njol/skript/SkriptCommand.java | 5 +- .../skript/doc/DocumentationGenerator.java | 7 +- .../skript/doc/DocumentationIdProvider.java | 14 +- .../ch/njol/skript/doc/HTMLGenerator.java | 1 - .../ch/njol/skript/doc/JSONGenerator.java | 214 +++++++++++++----- 5 files changed, 181 insertions(+), 60 deletions(-) diff --git a/src/main/java/ch/njol/skript/SkriptCommand.java b/src/main/java/ch/njol/skript/SkriptCommand.java index d27ec05ed45..a7d8d25dfc8 100644 --- a/src/main/java/ch/njol/skript/SkriptCommand.java +++ b/src/main/java/ch/njol/skript/SkriptCommand.java @@ -386,8 +386,9 @@ public boolean onCommand(CommandSender sender, Command command, String label, St outputDir.mkdirs(); Skript.info(sender, "Generating docs..."); - JSONGenerator jsonGenerator = new JSONGenerator(templateDir, outputDir); - jsonGenerator.generate(); + + JSONGenerator.of(Skript.getAddonInstance()) + .generate(outputDir.toPath().resolve("docs.json")); if (!templateDir.exists()) { Skript.info(sender, "JSON-only documentation generated!"); diff --git a/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java b/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java index 949e59f3ca5..1f253d71e63 100644 --- a/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java +++ b/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java @@ -1,10 +1,12 @@ package ch.njol.skript.doc; import java.io.File; +import java.nio.file.Path; /** - * Represents a class which generates a documentation format (like HTML or JSON) + * @deprecated Use {@link JSONGenerator} instead. */ +@Deprecated(forRemoval = true, since = "INSERT VERSION") public abstract class DocumentationGenerator { protected File templateDir; @@ -16,8 +18,9 @@ public DocumentationGenerator(File templateDir, File outputDir) { } /** - * Generates the documentation file + * Use {@link JSONGenerator#generate(Path)} instead. */ + @Deprecated(forRemoval = true, since = "INSERT VERSION") public abstract void generate(); } diff --git a/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java b/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java index 35a01c143b3..a46028ed476 100644 --- a/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java +++ b/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java @@ -12,6 +12,7 @@ import ch.njol.skript.lang.function.Functions; import ch.njol.skript.registrations.Classes; import org.skriptlang.skript.lang.structure.Structure; +import org.skriptlang.skript.registration.SyntaxInfo; import java.util.Arrays; import java.util.Iterator; @@ -62,7 +63,16 @@ private static int calculateCollisionCount(Iterator potentialCo * @return the ID of the syntax element */ public static String getId(SyntaxElementInfo syntaxInfo) { - Class syntaxClass = syntaxInfo.getElementClass(); + return getId((SyntaxInfo) syntaxInfo); + } + + /** + * Gets the documentation ID of a syntax element + * @param syntaxInfo the SyntaxInfo to get the ID of + * @return the ID of the syntax element + */ + public static String getId(SyntaxInfo syntaxInfo) { + Class syntaxClass = syntaxInfo.type(); Iterator> syntaxElementIterator; if (Effect.class.isAssignableFrom(syntaxClass)) { syntaxElementIterator = Skript.getEffects().iterator(); @@ -79,7 +89,7 @@ public static String getId(SyntaxElementInfo syntaxInfo) { } int collisionCount = calculateCollisionCount(syntaxElementIterator, elementInfo -> elementInfo.getElementClass() == syntaxClass, - elementInfo -> Arrays.equals(elementInfo.getPatterns(), syntaxInfo.getPatterns())); + elementInfo -> Arrays.equals(elementInfo.getPatterns(), syntaxInfo.patterns().toArray(new String[0]))); DocumentationId documentationIdAnnotation = syntaxClass.getAnnotation(DocumentationId.class); if (documentationIdAnnotation == null) { return addCollisionSuffix(syntaxClass.getSimpleName(), collisionCount); diff --git a/src/main/java/ch/njol/skript/doc/HTMLGenerator.java b/src/main/java/ch/njol/skript/doc/HTMLGenerator.java index 163a57b2824..ad9666ebab6 100644 --- a/src/main/java/ch/njol/skript/doc/HTMLGenerator.java +++ b/src/main/java/ch/njol/skript/doc/HTMLGenerator.java @@ -37,7 +37,6 @@ /** * Template engine, primarily used for generating Skript documentation * pages by combining data from annotations and templates. - * */ public class HTMLGenerator extends DocumentationGenerator { diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index d30d0f039ac..5b986fe91f8 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -1,16 +1,17 @@ package ch.njol.skript.doc; import ch.njol.skript.Skript; +import ch.njol.skript.SkriptAddon; import ch.njol.skript.classes.ClassInfo; -import ch.njol.skript.lang.SkriptEventInfo; +import ch.njol.skript.lang.Expression; import ch.njol.skript.lang.SyntaxElement; -import ch.njol.skript.lang.SyntaxElementInfo; import ch.njol.skript.lang.function.Functions; import ch.njol.skript.lang.function.JavaFunction; import ch.njol.skript.registrations.Classes; import ch.njol.skript.registrations.EventValues; import ch.njol.skript.registrations.EventValues.EventValueInfo; import ch.njol.skript.util.Version; +import com.google.common.base.Preconditions; import com.google.common.collect.Multimap; import com.google.gson.*; import org.bukkit.event.Cancellable; @@ -18,8 +19,12 @@ import org.bukkit.event.block.BlockCanBuildEvent; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +import org.skriptlang.skript.bukkit.registration.BukkitRegistryKeys; +import org.skriptlang.skript.bukkit.registration.BukkitSyntaxInfos; import org.skriptlang.skript.lang.structure.Structure; -import org.skriptlang.skript.lang.structure.StructureInfo; +import org.skriptlang.skript.registration.DefaultSyntaxInfos; +import org.skriptlang.skript.registration.SyntaxInfo; +import org.skriptlang.skript.registration.SyntaxRegistry; import java.io.File; import java.io.IOException; @@ -36,7 +41,7 @@ public class JSONGenerator extends DocumentationGenerator { /** * The current version of the JSON generator */ - public static final Version JSON_VERSION = new Version(1, 1); + public static final Version JSON_VERSION = new Version(2, 0); private static final Gson GSON = new GsonBuilder() .disableHtmlEscaping() @@ -44,8 +49,33 @@ public class JSONGenerator extends DocumentationGenerator { .serializeNulls() .create(); + /** + * Creates a {@link JSONGenerator} for the specified addon. + * + * @param addon The addon. + * @return The created {@link JSONGenerator}. + */ + public static JSONGenerator of(@NotNull SkriptAddon addon) { + return new JSONGenerator(addon); + } + + private final @NotNull SkriptAddon addon; + + private JSONGenerator(@NotNull SkriptAddon addon) { + super(new File(""), new File("")); + + Preconditions.checkNotNull(addon, "addon cannot be null"); + + this.addon = addon; + } + + /** + * @deprecated Use {@link #of(SkriptAddon)} instead. + */ + @Deprecated(forRemoval = true, since = "INSERT VERSION") public JSONGenerator(File templateDir, File outputDir) { super(templateDir, outputDir); + addon = Skript.getAddonInstance(); } /** @@ -80,8 +110,8 @@ private static JsonArray convertToJsonArray(String @Nullable ... strings) { * @param syntaxInfo the syntax info element to generate the documentation object of * @return the JsonObject representing the documentation of the provided syntax element */ - private static JsonObject generatedAnnotatedElement(SyntaxElementInfo syntaxInfo) { - Class syntaxClass = syntaxInfo.getElementClass(); + private static JsonObject generatedAnnotatedElement(SyntaxInfo syntaxInfo) { + Class syntaxClass = syntaxInfo.type(); Name name = syntaxClass.getAnnotation(Name.class); if (name == null || syntaxClass.getAnnotation(NoDoc.class) != null) return null; @@ -99,7 +129,7 @@ private static JsonObject generatedAnnotatedElement(SyntaxElementInfo syntaxI Description description = syntaxClass.getAnnotation(Description.class); syntaxJsonObject.add("description", description == null ? null : convertToJsonArray(description.value())); - syntaxJsonObject.add("patterns", cleanPatterns(syntaxInfo.getPatterns())); + syntaxJsonObject.add("patterns", cleanPatterns(syntaxInfo.patterns().toArray(new String[0]))); if (syntaxClass.isAnnotationPresent(Examples.class)) { @NotNull Examples examplesAnnotation = syntaxClass.getAnnotation(Examples.class); @@ -117,8 +147,7 @@ private static JsonObject generatedAnnotatedElement(SyntaxElementInfo syntaxI syntaxJsonObject.add("examples", null); } - Events events = syntaxClass.getAnnotation(Events.class); - syntaxJsonObject.add("events", events == null ? null : convertToJsonArray(events.value())); + syntaxJsonObject.add("events", getAnnotatedEvents(syntaxClass.getAnnotation(Events.class))); RequiredPlugins requirements = syntaxClass.getAnnotation(RequiredPlugins.class); syntaxJsonObject.add("requirements", requirements == null ? null : convertToJsonArray(requirements.value())); @@ -126,28 +155,88 @@ private static JsonObject generatedAnnotatedElement(SyntaxElementInfo syntaxI Keywords keywords = syntaxClass.getAnnotation(Keywords.class); syntaxJsonObject.add("keywords", keywords == null ? null : convertToJsonArray(keywords.value())); + if (Expression.class.isAssignableFrom(syntaxInfo.type())) { + syntaxJsonObject.add("returns", getExpressionReturnTypes((Expression) syntaxInfo.instance())); + } + return syntaxJsonObject; } + /** + * Returns the formatted events based on the {@link Events} annotation. + * + * @param events The events annotation. + * @return A json array with the formatted events value, or null if there is no annotation. + */ + private static @Nullable JsonArray getAnnotatedEvents(Events events) { + if (events == null || events.value() == null) { + return null; + } + + JsonArray array = new JsonArray(); + + for (String event : events.value()) { + JsonObject object = new JsonObject(); + + object.addProperty("id", event); + object.addProperty("name", event); + + array.add(object); + } + + return array; + } + + /** + * Attempts to get an {@link Expression}'s return types by creating a new instance + * and calling {@link Expression#possibleReturnTypes()}. + * If the type cannot be determined statically, will return {@code null}. + * + * @param expression The expression class. + * @return The return types, or null if they are not static. + */ + private static @Nullable JsonArray getExpressionReturnTypes(Expression expression) { + try { + JsonArray types = new JsonArray(); + + for (Class type : expression.possibleReturnTypes()) { + ClassInfo exact = Classes.getExactClassInfo(type); + + if (exact == null) { + continue; + } + + JsonObject object = new JsonObject(); + object.addProperty("id", exact.getCodeName()); + object.addProperty("name", exact.getName().getSingular()); + types.add(object); + } + + return types; + } catch (Exception e) { + return null; + } + } + /** * Generates the documentation JsonObject for an event * * @param info the event to generate the documentation object for * @return a documentation JsonObject for the event */ - private static JsonObject generateEventElement(SkriptEventInfo info) { + private static JsonObject generateEventElement(BukkitSyntaxInfos.Event info) { JsonObject syntaxJsonObject = new JsonObject(); syntaxJsonObject.addProperty("id", DocumentationIdProvider.getId(info)); - syntaxJsonObject.addProperty("name", info.getName()); + syntaxJsonObject.addProperty("name", info.name()); syntaxJsonObject.addProperty("cancellable", isCancellable(info)); - syntaxJsonObject.add("since", convertToJsonArray(info.getSince())); - syntaxJsonObject.add("patterns", cleanPatterns(info.getPatterns())); - syntaxJsonObject.add("description", convertToJsonArray(info.getDescription())); - syntaxJsonObject.add("requirements", convertToJsonArray(info.getRequiredPlugins())); - syntaxJsonObject.add("examples", convertToJsonArray(info.getExamples())); + syntaxJsonObject.add("since", convertToJsonArray(info.since().toArray(new String[0]))); + syntaxJsonObject.add("patterns", cleanPatterns(info.patterns().toArray(new String[0]))); + syntaxJsonObject.add("description", convertToJsonArray(info.description().toArray(new String[0]))); + syntaxJsonObject.add("requirements", convertToJsonArray(info.requiredPlugins().toArray(new String[0]))); + syntaxJsonObject.add("examples", convertToJsonArray(info.examples().toArray(new String[0]))); syntaxJsonObject.add("eventValues", getEventValues(info)); - syntaxJsonObject.add("keywords", convertToJsonArray(info.getKeywords())); + syntaxJsonObject.add("keywords", convertToJsonArray(info.keywords().toArray(new String[0]))); return syntaxJsonObject; } @@ -158,11 +247,11 @@ private static JsonObject generateEventElement(SkriptEventInfo info) { * @param info the event to generate the event values of * @return a JsonArray containing the documentation JsonObjects for each event value */ - private static JsonArray getEventValues(SkriptEventInfo info) { + private static JsonArray getEventValues(BukkitSyntaxInfos.Event info) { Set eventValues = new HashSet<>(); Multimap, EventValueInfo> allEventValues = EventValues.getPerEventEventValues(); - for (Class supportedEvent : info.events) { + for (Class supportedEvent : info.events()) { for (Class event : allEventValues.keySet()) { if (!event.isAssignableFrom(supportedEvent)) { continue; @@ -227,9 +316,9 @@ private static JsonArray getEventValues(SkriptEventInfo info) { * @param info the event to check * @return true if the event is cancellable, false otherwise */ - private static boolean isCancellable(SkriptEventInfo info) { + private static boolean isCancellable(BukkitSyntaxInfos.Event info) { boolean cancellable = false; - for (Class event : info.events) { + for (Class event : info.events()) { if (Cancellable.class.isAssignableFrom(event) || BlockCanBuildEvent.class.isAssignableFrom(event)) { cancellable = true; break; @@ -245,10 +334,10 @@ private static boolean isCancellable(SkriptEventInfo info) { * @param infos the structures to generate documentation for * @return a JsonArray containing the documentation JsonObjects for each structure */ - private static > JsonArray generateStructureElementArray(Iterator infos) { + private static > JsonArray generateStructureElementArray(Collection infos) { JsonArray syntaxArray = new JsonArray(); - infos.forEachRemaining(info -> { - if (info instanceof SkriptEventInfo eventInfo) { + infos.forEach(info -> { + if (info instanceof BukkitSyntaxInfos.Event eventInfo) { syntaxArray.add(generateEventElement(eventInfo)); } else { JsonObject structureElementJsonObject = generatedAnnotatedElement(info); @@ -265,9 +354,9 @@ private static > JsonArray generate * @param infos the syntax elements to generate documentation for * @return a JsonArray containing the documentation JsonObjects for each syntax element */ - private static > JsonArray generateSyntaxElementArray(Iterator infos) { + private static > JsonArray generateSyntaxElementArray(Collection infos) { JsonArray syntaxArray = new JsonArray(); - infos.forEachRemaining(info -> { + infos.forEach(info -> { JsonObject syntaxJsonObject = generatedAnnotatedElement(info); if (syntaxJsonObject != null) syntaxArray.add(syntaxJsonObject); @@ -325,7 +414,7 @@ private static JsonObject generateFunctionElement(JavaFunction function) { functionJsonObject.addProperty("id", DocumentationIdProvider.getId(function)); functionJsonObject.addProperty("name", function.getName()); functionJsonObject.addProperty("since", function.getSince()); - functionJsonObject.add("returnType", getReturnType(function)); + functionJsonObject.add("returns", getFunctionReturnType(function)); functionJsonObject.add("description", convertToJsonArray(function.getDescription())); functionJsonObject.add("examples", convertToJsonArray(function.getExamples())); @@ -341,7 +430,7 @@ private static JsonObject generateFunctionElement(JavaFunction function) { * @param function the JavaFunction to get the return type of * @return the JsonObject representing the return type of the JavaFunction */ - private static JsonObject getReturnType(JavaFunction function) { + private static JsonObject getFunctionReturnType(JavaFunction function) { JsonObject object = new JsonObject(); ClassInfo returnType = function.getReturnType(); @@ -383,40 +472,59 @@ private static JsonArray cleanPatterns(String... strings) { } /** - * Writes the documentation JsonObject to an output path + * Generates the json documentation for this addon at the specified path. * - * @param outputPath the path to write the documentation to - * @param jsonDocs the documentation JsonObject + * @param output The output path. */ - private void saveDocs(Path outputPath, JsonObject jsonDocs) { - try { - Files.writeString(outputPath, GSON.toJson(jsonDocs)); - } catch (IOException exception) { - //noinspection ThrowableNotThrown - Skript.exception(exception, "An error occurred while trying to generate JSON documentation"); - } - } - - @Override - public void generate() { + public void generate(Path output) throws IOException { JsonObject jsonDocs = new JsonObject(); - jsonDocs.addProperty("skriptVersion", Skript.getVersion().toString()); jsonDocs.add("version", getVersion()); - jsonDocs.add("conditions", generateSyntaxElementArray(Skript.getConditions().iterator())); - jsonDocs.add("effects", generateSyntaxElementArray(Skript.getEffects().iterator())); - jsonDocs.add("expressions", generateSyntaxElementArray(Skript.getExpressions())); - jsonDocs.add("events", generateStructureElementArray(Skript.getEvents().iterator())); - jsonDocs.add("classes", generateClassInfoArray(Classes.getClassInfos().iterator())); + jsonDocs.add("addon", getAddon()); + jsonDocs.add("conditions", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.CONDITION))); + jsonDocs.add("effects", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.EFFECT))); + jsonDocs.add("expressions", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.EXPRESSION))); + jsonDocs.add("events", generateStructureElementArray(addon.syntaxRegistry().syntaxes(BukkitRegistryKeys.EVENT))); + jsonDocs.add("types", generateClassInfoArray(Classes.getClassInfos().iterator())); + + Stream> structuresExcludingEvents = addon.syntaxRegistry() + .syntaxes(SyntaxRegistry.STRUCTURE) + .stream() + .filter(structureInfo -> !(structureInfo instanceof BukkitSyntaxInfos.Event)); - Stream> structuresExcludingEvents = Skript.getStructures().stream() - .filter(structureInfo -> !(structureInfo instanceof SkriptEventInfo)); - jsonDocs.add("structures", generateStructureElementArray(structuresExcludingEvents.iterator())); - jsonDocs.add("sections", generateSyntaxElementArray(Skript.getSections().iterator())); + jsonDocs.add("structures", generateStructureElementArray(structuresExcludingEvents.toList())); + jsonDocs.add("sections", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.SECTION))); jsonDocs.add("functions", generateFunctionArray(Functions.getJavaFunctions().iterator())); - saveDocs(outputDir.toPath().resolve("docs.json"), jsonDocs); + Files.writeString(output, GSON.toJson(jsonDocs)); + } + + /** + * Gets the json object representing the addon. + * + * @return The json object representing the addon. + */ + private JsonObject getAddon() { + JsonObject object = new JsonObject(); + + object.addProperty("name", this.addon.name()); + object.addProperty("version", this.addon.version.toString()); + + return object; + } + + /** + * @deprecated Use {@link #generate(Path)} instead. + */ + @Deprecated(forRemoval = true, since = "INSERT VERSION") + @Override + public void generate() { + try { + generate(outputDir.toPath()); + } catch (IOException ex) { + Skript.exception(ex, "An error occurred while trying to generate JSON documentation"); + } } } From b80b77ac938dacdeef7c202522b1d8eaf8446311 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Wed, 6 Aug 2025 20:25:49 +0200 Subject: [PATCH 02/13] add docs --- .../ch/njol/skript/doc/JSONGenerator.java | 46 ++++++++++--------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index 5b986fe91f8..c977e109421 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -50,23 +50,23 @@ public class JSONGenerator extends DocumentationGenerator { .create(); /** - * Creates a {@link JSONGenerator} for the specified addon. + * Creates a {@link JSONGenerator} for the specified source. * - * @param addon The addon. + * @param source The addon to use as source. * @return The created {@link JSONGenerator}. */ - public static JSONGenerator of(@NotNull SkriptAddon addon) { - return new JSONGenerator(addon); + public static JSONGenerator of(@NotNull SkriptAddon source) { + return new JSONGenerator(source); } - private final @NotNull SkriptAddon addon; + private final @NotNull SkriptAddon source; - private JSONGenerator(@NotNull SkriptAddon addon) { + private JSONGenerator(@NotNull SkriptAddon source) { super(new File(""), new File("")); - Preconditions.checkNotNull(addon, "addon cannot be null"); + Preconditions.checkNotNull(source, "addon cannot be null"); - this.addon = addon; + this.source = source; } /** @@ -75,7 +75,7 @@ private JSONGenerator(@NotNull SkriptAddon addon) { @Deprecated(forRemoval = true, since = "INSERT VERSION") public JSONGenerator(File templateDir, File outputDir) { super(templateDir, outputDir); - addon = Skript.getAddonInstance(); + source = Skript.getAddonInstance(); } /** @@ -430,7 +430,8 @@ private static JsonObject generateFunctionElement(JavaFunction function) { * @param function the JavaFunction to get the return type of * @return the JsonObject representing the return type of the JavaFunction */ - private static JsonObject getFunctionReturnType(JavaFunction function) { + private static JsonArray getFunctionReturnType(JavaFunction function) { + JsonArray array = new JsonArray(); JsonObject object = new JsonObject(); ClassInfo returnType = function.getReturnType(); @@ -440,7 +441,9 @@ private static JsonObject getFunctionReturnType(JavaFunction function) { object.addProperty("id", DocumentationIdProvider.getId(returnType)); object.addProperty("name", Objects.requireNonNullElse(returnType.getDocName(), returnType.getCodeName())); - return object; + + array.add(object); + return array; } /** @@ -480,21 +483,20 @@ public void generate(Path output) throws IOException { JsonObject jsonDocs = new JsonObject(); jsonDocs.add("version", getVersion()); - jsonDocs.add("addon", getAddon()); - jsonDocs.add("conditions", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.CONDITION))); - jsonDocs.add("effects", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.EFFECT))); - jsonDocs.add("expressions", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.EXPRESSION))); - jsonDocs.add("events", generateStructureElementArray(addon.syntaxRegistry().syntaxes(BukkitRegistryKeys.EVENT))); + jsonDocs.add("source", getSource()); + jsonDocs.add("conditions", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.CONDITION))); + jsonDocs.add("effects", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.EFFECT))); + jsonDocs.add("expressions", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.EXPRESSION))); + jsonDocs.add("events", generateStructureElementArray(source.syntaxRegistry().syntaxes(BukkitRegistryKeys.EVENT))); jsonDocs.add("types", generateClassInfoArray(Classes.getClassInfos().iterator())); - Stream> structuresExcludingEvents = addon.syntaxRegistry() + Stream> structuresExcludingEvents = source.syntaxRegistry() .syntaxes(SyntaxRegistry.STRUCTURE) .stream() .filter(structureInfo -> !(structureInfo instanceof BukkitSyntaxInfos.Event)); jsonDocs.add("structures", generateStructureElementArray(structuresExcludingEvents.toList())); - jsonDocs.add("sections", generateSyntaxElementArray(addon.syntaxRegistry().syntaxes(SyntaxRegistry.SECTION))); - + jsonDocs.add("sections", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.SECTION))); jsonDocs.add("functions", generateFunctionArray(Functions.getJavaFunctions().iterator())); Files.writeString(output, GSON.toJson(jsonDocs)); @@ -505,11 +507,11 @@ public void generate(Path output) throws IOException { * * @return The json object representing the addon. */ - private JsonObject getAddon() { + private JsonObject getSource() { JsonObject object = new JsonObject(); - object.addProperty("name", this.addon.name()); - object.addProperty("version", this.addon.version.toString()); + object.addProperty("name", this.source.name()); + object.addProperty("version", this.source.version.toString()); return object; } From ea2ad5d72939e6aa3778fd586b2e858531b5fac9 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Wed, 6 Aug 2025 20:25:57 +0200 Subject: [PATCH 03/13] add StructEvent docs --- .../njol/skript/structures/StructEvent.java | 42 ++++++++++++++++++- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/src/main/java/ch/njol/skript/structures/StructEvent.java b/src/main/java/ch/njol/skript/structures/StructEvent.java index 5033a0be5fa..0c065d00611 100644 --- a/src/main/java/ch/njol/skript/structures/StructEvent.java +++ b/src/main/java/ch/njol/skript/structures/StructEvent.java @@ -1,7 +1,7 @@ package ch.njol.skript.structures; import ch.njol.skript.Skript; -import ch.njol.skript.doc.NoDoc; +import ch.njol.skript.doc.*; import ch.njol.skript.lang.Literal; import ch.njol.skript.lang.SkriptEvent; import ch.njol.skript.lang.SkriptEvent.ListeningBehavior; @@ -15,7 +15,45 @@ import java.util.Locale; -@NoDoc +@Name("Event") +@Description(""" + The structure used for listening to events. + + Optionally allows specifying whether to listen to events that have been cancelled and + allows specifying with which priority to listen to events. Events are called in the following order + of priorities. + + ``` + lowest -> low -> normal -> high -> highest -> monitor + ``` + + According to Paper, monitor events should avoid making modifications to the event, and should only + be used for monitoring the outcome of an event. + """) +@Example(""" + on load: + broadcast "loading!" + """) +@Example(""" + on join: + if {first-join::%player's uuid%} is not set: + set {first-join::%player's uuid%} to now + """) +@Example(""" + cancelled block break: + send "You can't break that here" to player + """) +@Example(""" + on join with priority lowest: + # called first + + on join: + # called second + + on join with priority highest: + # called last + """) +@Since({"1.0", "2.9 (listening to cancellable events)"}) public class StructEvent extends Structure { static { From 1f0ed4421b6d86ccc490ce6a1114562f8e2c60e8 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Thu, 7 Aug 2025 16:41:16 +0200 Subject: [PATCH 04/13] requested changes --- .../java/ch/njol/skript/SkriptCommand.java | 2 +- .../ch/njol/skript/doc/JSONGenerator.java | 78 ++++++++----------- 2 files changed, 34 insertions(+), 46 deletions(-) diff --git a/src/main/java/ch/njol/skript/SkriptCommand.java b/src/main/java/ch/njol/skript/SkriptCommand.java index a7d8d25dfc8..5592fed5537 100644 --- a/src/main/java/ch/njol/skript/SkriptCommand.java +++ b/src/main/java/ch/njol/skript/SkriptCommand.java @@ -387,7 +387,7 @@ public boolean onCommand(CommandSender sender, Command command, String label, St Skript.info(sender, "Generating docs..."); - JSONGenerator.of(Skript.getAddonInstance()) + JSONGenerator.of(Skript.instance()) .generate(outputDir.toPath().resolve("docs.json")); if (!templateDir.exists()) { diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index c977e109421..79045fb5ad6 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -1,9 +1,7 @@ package ch.njol.skript.doc; import ch.njol.skript.Skript; -import ch.njol.skript.SkriptAddon; import ch.njol.skript.classes.ClassInfo; -import ch.njol.skript.lang.Expression; import ch.njol.skript.lang.SyntaxElement; import ch.njol.skript.lang.function.Functions; import ch.njol.skript.lang.function.JavaFunction; @@ -17,8 +15,11 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.block.BlockCanBuildEvent; +import org.bukkit.plugin.java.JavaPlugin; +import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +import org.skriptlang.skript.addon.SkriptAddon; import org.skriptlang.skript.bukkit.registration.BukkitRegistryKeys; import org.skriptlang.skript.bukkit.registration.BukkitSyntaxInfos; import org.skriptlang.skript.lang.structure.Structure; @@ -31,7 +32,6 @@ import java.nio.file.Files; import java.nio.file.Path; import java.util.*; -import java.util.stream.Stream; /** * Generates JSON docs @@ -55,6 +55,7 @@ public class JSONGenerator extends DocumentationGenerator { * @param source The addon to use as source. * @return The created {@link JSONGenerator}. */ + @Contract("_ -> new") public static JSONGenerator of(@NotNull SkriptAddon source) { return new JSONGenerator(source); } @@ -75,7 +76,7 @@ private JSONGenerator(@NotNull SkriptAddon source) { @Deprecated(forRemoval = true, since = "INSERT VERSION") public JSONGenerator(File templateDir, File outputDir) { super(templateDir, outputDir); - source = Skript.getAddonInstance(); + source = Skript.instance(); } /** @@ -155,8 +156,8 @@ private static JsonObject generatedAnnotatedElement(SyntaxInfo syntaxInfo) { Keywords keywords = syntaxClass.getAnnotation(Keywords.class); syntaxJsonObject.add("keywords", keywords == null ? null : convertToJsonArray(keywords.value())); - if (Expression.class.isAssignableFrom(syntaxInfo.type())) { - syntaxJsonObject.add("returns", getExpressionReturnTypes((Expression) syntaxInfo.instance())); + if (syntaxInfo instanceof DefaultSyntaxInfos.Expression expression) { + syntaxJsonObject.add("returns", getExpressionReturnTypes(expression)); } return syntaxJsonObject; @@ -188,34 +189,22 @@ private static JsonObject generatedAnnotatedElement(SyntaxInfo syntaxInfo) { } /** - * Attempts to get an {@link Expression}'s return types by creating a new instance - * and calling {@link Expression#possibleReturnTypes()}. - * If the type cannot be determined statically, will return {@code null}. + * Gets an {@link DefaultSyntaxInfos.Expression}'s return type. * * @param expression The expression class. - * @return The return types, or null if they are not static. + * @return An object with the return type. */ - private static @Nullable JsonArray getExpressionReturnTypes(Expression expression) { - try { - JsonArray types = new JsonArray(); - - for (Class type : expression.possibleReturnTypes()) { - ClassInfo exact = Classes.getExactClassInfo(type); - - if (exact == null) { - continue; - } + private static @Nullable JsonObject getExpressionReturnTypes(DefaultSyntaxInfos.Expression expression) { + ClassInfo exact = Classes.getExactClassInfo(expression.returnType()); - JsonObject object = new JsonObject(); - object.addProperty("id", exact.getCodeName()); - object.addProperty("name", exact.getName().getSingular()); - types.add(object); - } - - return types; - } catch (Exception e) { + if (exact == null) { return null; } + + JsonObject object = new JsonObject(); + object.addProperty("id", exact.getCodeName()); + object.addProperty("name", exact.getName().getSingular()); + return object; } /** @@ -430,8 +419,7 @@ private static JsonObject generateFunctionElement(JavaFunction function) { * @param function the JavaFunction to get the return type of * @return the JsonObject representing the return type of the JavaFunction */ - private static JsonArray getFunctionReturnType(JavaFunction function) { - JsonArray array = new JsonArray(); + private static JsonObject getFunctionReturnType(JavaFunction function) { JsonObject object = new JsonObject(); ClassInfo returnType = function.getReturnType(); @@ -442,8 +430,7 @@ private static JsonArray getFunctionReturnType(JavaFunction function) { object.addProperty("id", DocumentationIdProvider.getId(returnType)); object.addProperty("name", Objects.requireNonNullElse(returnType.getDocName(), returnType.getCodeName())); - array.add(object); - return array; + return object; } /** @@ -477,9 +464,11 @@ private static JsonArray cleanPatterns(String... strings) { /** * Generates the json documentation for this addon at the specified path. * - * @param output The output path. + * @param path The output path. */ - public void generate(Path output) throws IOException { + public void generate(@NotNull Path path) throws IOException { + Preconditions.checkNotNull(path, "path cannot be null"); + JsonObject jsonDocs = new JsonObject(); jsonDocs.add("version", getVersion()); @@ -488,18 +477,12 @@ public void generate(Path output) throws IOException { jsonDocs.add("effects", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.EFFECT))); jsonDocs.add("expressions", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.EXPRESSION))); jsonDocs.add("events", generateStructureElementArray(source.syntaxRegistry().syntaxes(BukkitRegistryKeys.EVENT))); - jsonDocs.add("types", generateClassInfoArray(Classes.getClassInfos().iterator())); - - Stream> structuresExcludingEvents = source.syntaxRegistry() - .syntaxes(SyntaxRegistry.STRUCTURE) - .stream() - .filter(structureInfo -> !(structureInfo instanceof BukkitSyntaxInfos.Event)); - - jsonDocs.add("structures", generateStructureElementArray(structuresExcludingEvents.toList())); + jsonDocs.add("structures", generateStructureElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.STRUCTURE))); jsonDocs.add("sections", generateSyntaxElementArray(source.syntaxRegistry().syntaxes(SyntaxRegistry.SECTION))); + jsonDocs.add("types", generateClassInfoArray(Classes.getClassInfos().iterator())); jsonDocs.add("functions", generateFunctionArray(Functions.getJavaFunctions().iterator())); - Files.writeString(output, GSON.toJson(jsonDocs)); + Files.writeString(path, GSON.toJson(jsonDocs)); } /** @@ -510,8 +493,13 @@ public void generate(Path output) throws IOException { private JsonObject getSource() { JsonObject object = new JsonObject(); - object.addProperty("name", this.source.name()); - object.addProperty("version", this.source.version.toString()); + object.addProperty("name", source.name()); + try { + JavaPlugin plugin = JavaPlugin.getProvidingPlugin(source.source()); + object.addProperty("version", plugin.getDescription().getVersion()); + } catch (Exception ex) { + object.add("version", null); + } return object; } From bcae0c1249f53a9b427b193f0dd2501ceffbafa2 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Mon, 11 Aug 2025 01:11:43 +0200 Subject: [PATCH 05/13] fix default values for DocumentationGenerator --- src/main/java/ch/njol/skript/doc/JSONGenerator.java | 2 +- 1 file changed, 1 insertion(+), 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 79045fb5ad6..aa712bf0887 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -63,7 +63,7 @@ public static JSONGenerator of(@NotNull SkriptAddon source) { private final @NotNull SkriptAddon source; private JSONGenerator(@NotNull SkriptAddon source) { - super(new File(""), new File("")); + super(Documentation.getDocsTemplateDirectory(), Documentation.getDocsOutputDirectory()); Preconditions.checkNotNull(source, "addon cannot be null"); From 2012ed38c8ebc2cfd164edbc57d92b416be1f758 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:19:15 +0200 Subject: [PATCH 06/13] github why won't you work --- src/main/java/ch/njol/skript/doc/JSONGenerator.java | 7 ++++++- 1 file changed, 6 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 aa712bf0887..da4307d4aef 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -482,7 +482,12 @@ public void generate(@NotNull Path path) throws IOException { jsonDocs.add("types", generateClassInfoArray(Classes.getClassInfos().iterator())); jsonDocs.add("functions", generateFunctionArray(Functions.getJavaFunctions().iterator())); - Files.writeString(path, GSON.toJson(jsonDocs)); + try { + Files.writeString(path, GSON.toJson(jsonDocs)); + } catch (IOException ex) { + Skript.exception(ex, "An error occurred while trying to generate JSON documentation"); + throw new IOException(ex); + } } /** From e62aa57b34f1672090e917912a7bd028d02d713f Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:32:52 +0200 Subject: [PATCH 07/13] attempt to fix getting skript version in generate-docs action --- .github/workflows/docs/generate-docs/action.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/docs/generate-docs/action.yml b/.github/workflows/docs/generate-docs/action.yml index 2470f852450..27504302bec 100644 --- a/.github/workflows/docs/generate-docs/action.yml +++ b/.github/workflows/docs/generate-docs/action.yml @@ -52,10 +52,8 @@ runs: find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \; } - # this should be replaced with a more reliable jq command, - # but it can't be right now because docs.json is actually not valid json. get_skript_version_of_directory() { - grep skriptVersion "$1/docs.json" | cut -d\" -f 4 + jq '.source.version' docs.json } if [ -d "${DOCS_REPO_DIR}/docs/templates" ] From 46b86401ab4d27bb84c8e7def7a80460c5659b9f Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:35:30 +0200 Subject: [PATCH 08/13] attempt to fix getting skript version in generate-docs action --- .github/workflows/docs/generate-docs/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs/generate-docs/action.yml b/.github/workflows/docs/generate-docs/action.yml index 27504302bec..f730f3ad098 100644 --- a/.github/workflows/docs/generate-docs/action.yml +++ b/.github/workflows/docs/generate-docs/action.yml @@ -53,7 +53,7 @@ runs: } get_skript_version_of_directory() { - jq '.source.version' docs.json + jq ".source.version" "$1/docs.json" } if [ -d "${DOCS_REPO_DIR}/docs/templates" ] From 446f7d6d403c86ea40dc1a4b21beb8b4d3507a2c Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Wed, 20 Aug 2025 20:38:02 +0200 Subject: [PATCH 09/13] requested changes --- src/main/java/ch/njol/skript/doc/JSONGenerator.java | 4 ++++ src/main/java/ch/njol/skript/structures/StructEvent.java | 8 +++++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index da4307d4aef..a5c01a3d32d 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -242,6 +242,10 @@ private static JsonArray getEventValues(BukkitSyntaxInfos.Event info) { Multimap, EventValueInfo> allEventValues = EventValues.getPerEventEventValues(); for (Class supportedEvent : info.events()) { for (Class event : allEventValues.keySet()) { + if (event == null) { + continue; + } + if (!event.isAssignableFrom(supportedEvent)) { continue; } diff --git a/src/main/java/ch/njol/skript/structures/StructEvent.java b/src/main/java/ch/njol/skript/structures/StructEvent.java index 0c065d00611..afe7080e5d1 100644 --- a/src/main/java/ch/njol/skript/structures/StructEvent.java +++ b/src/main/java/ch/njol/skript/structures/StructEvent.java @@ -19,15 +19,17 @@ @Description(""" The structure used for listening to events. - Optionally allows specifying whether to listen to events that have been cancelled and - allows specifying with which priority to listen to events. Events are called in the following order + Optionally allows specifying whether to listen to events that have been cancelled or events that have + been cancelled, and then were uncancelled again. + + Also allows specifying with which priority to listen to events. Events are called in the following order of priorities. ``` lowest -> low -> normal -> high -> highest -> monitor ``` - According to Paper, monitor events should avoid making modifications to the event, and should only + Modifying event-values or cancelling events is not supported when using the 'monitor' priority. It should only be used for monitoring the outcome of an event. """) @Example(""" From 1d70331d2f724787c34d0e61146f553f11967768 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Thu, 21 Aug 2025 15:21:53 +0200 Subject: [PATCH 10/13] requested changes --- .../java/ch/njol/skript/structures/StructEvent.java | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/main/java/ch/njol/skript/structures/StructEvent.java b/src/main/java/ch/njol/skript/structures/StructEvent.java index afe7080e5d1..a70e589831f 100644 --- a/src/main/java/ch/njol/skript/structures/StructEvent.java +++ b/src/main/java/ch/njol/skript/structures/StructEvent.java @@ -19,11 +19,9 @@ @Description(""" The structure used for listening to events. - Optionally allows specifying whether to listen to events that have been cancelled or events that have - been cancelled, and then were uncancelled again. - - Also allows specifying with which priority to listen to events. Events are called in the following order - of priorities. + Optionally allows specifying whether to listen to events that have been cancelled, + and allows specifying with which priority to listen to events. + Events are called in the following order of priorities. ``` lowest -> low -> normal -> high -> highest -> monitor @@ -55,7 +53,7 @@ on join with priority highest: # called last """) -@Since({"1.0", "2.9 (listening to cancellable events)"}) +@Since({"1.0", "2.6 (per-event priority)", "2.9 (listening to cancellable events)"}) public class StructEvent extends Structure { static { From bb3d7bcede7c529d5b73480e1232c9c0f5b1335a Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Thu, 21 Aug 2025 23:54:26 +0200 Subject: [PATCH 11/13] requested changes --- .../ch/njol/skript/doc/JSONGenerator.java | 130 +++++++++--------- 1 file changed, 65 insertions(+), 65 deletions(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index a5c01a3d32d..9ec96df6605 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -12,9 +12,11 @@ import com.google.common.base.Preconditions; import com.google.common.collect.Multimap; import com.google.gson.*; +import org.bukkit.Bukkit; import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.block.BlockCanBuildEvent; +import org.bukkit.plugin.Plugin; import org.bukkit.plugin.java.JavaPlugin; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; @@ -32,6 +34,7 @@ import java.nio.file.Files; import java.nio.file.Path; import java.util.*; +import java.util.Map.Entry; /** * Generates JSON docs @@ -156,7 +159,7 @@ private static JsonObject generatedAnnotatedElement(SyntaxInfo syntaxInfo) { Keywords keywords = syntaxClass.getAnnotation(Keywords.class); syntaxJsonObject.add("keywords", keywords == null ? null : convertToJsonArray(keywords.value())); - if (syntaxInfo instanceof DefaultSyntaxInfos.Expression expression) { + if (syntaxInfo instanceof SyntaxInfo.Expression expression) { syntaxJsonObject.add("returns", getExpressionReturnTypes(expression)); } @@ -194,12 +197,8 @@ private static JsonObject generatedAnnotatedElement(SyntaxInfo syntaxInfo) { * @param expression The expression class. * @return An object with the return type. */ - private static @Nullable JsonObject getExpressionReturnTypes(DefaultSyntaxInfos.Expression expression) { - ClassInfo exact = Classes.getExactClassInfo(expression.returnType()); - - if (exact == null) { - return null; - } + private static @NotNull JsonObject getExpressionReturnTypes(DefaultSyntaxInfos.Expression expression) { + ClassInfo exact = Classes.getSuperClassInfo(expression.returnType()); JsonObject object = new JsonObject(); object.addProperty("id", exact.getCodeName()); @@ -241,7 +240,10 @@ private static JsonArray getEventValues(BukkitSyntaxInfos.Event info) { Multimap, EventValueInfo> allEventValues = EventValues.getPerEventEventValues(); for (Class supportedEvent : info.events()) { - for (Class event : allEventValues.keySet()) { + for (Entry, EventValueInfo> entry : allEventValues.entries()) { + Class event = entry.getKey(); + EventValueInfo eventValueInfo = entry.getValue(); + if (event == null) { continue; } @@ -250,45 +252,37 @@ private static JsonArray getEventValues(BukkitSyntaxInfos.Event info) { continue; } - Collection> eventValueInfos = allEventValues.get(event); - - for (EventValueInfo eventValueInfo : eventValueInfos) { - Class[] excludes = eventValueInfo.excludes(); - if (excludes != null && Set.of(excludes).contains(event)) { - continue; - } - - Class valueClass = eventValueInfo.valueClass(); - ClassInfo classInfo; - if (valueClass.isArray()) { - classInfo = Classes.getExactClassInfo(valueClass.componentType()); - } else { - classInfo = Classes.getExactClassInfo(valueClass); - } - - if (classInfo == null) { - continue; - } - - String name = classInfo.getName().getSingular(); - if (valueClass.isArray()) { - name = classInfo.getName().getPlural(); - } - if (name.isBlank()) { - continue; - } - - if (eventValueInfo.time() == EventValues.TIME_PAST) { - name = "past " + name; - } else if (eventValueInfo.time() == EventValues.TIME_FUTURE) { - name = "future " + name; - } - - JsonObject object = new JsonObject(); - object.addProperty("id", DocumentationIdProvider.getId(classInfo)); - object.addProperty("name", name.toLowerCase(Locale.ENGLISH)); - eventValues.add(object); + Class[] excludes = eventValueInfo.excludes(); + if (excludes != null && Set.of(excludes).contains(event)) { + continue; + } + + Class valueClass = eventValueInfo.valueClass(); + ClassInfo classInfo; + if (valueClass.isArray()) { + classInfo = Classes.getSuperClassInfo(valueClass.componentType()); + } else { + classInfo = Classes.getSuperClassInfo(valueClass); + } + + String name = classInfo.getName().getSingular(); + if (valueClass.isArray()) { + name = classInfo.getName().getPlural(); + } + if (name.isBlank()) { + continue; + } + + if (eventValueInfo.time() == EventValues.TIME_PAST) { + name = "past " + name; + } else if (eventValueInfo.time() == EventValues.TIME_FUTURE) { + name = "future " + name; } + + JsonObject object = new JsonObject(); + object.addProperty("id", DocumentationIdProvider.getId(classInfo)); + object.addProperty("name", name.toLowerCase(Locale.ENGLISH)); + eventValues.add(object); } } @@ -465,6 +459,31 @@ private static JsonArray cleanPatterns(String... strings) { return convertToJsonArray(strings); } + /** + * Gets the json object representing the addon. + * + * @return The json object representing the addon. + */ + private JsonObject getSource() { + JsonObject object = new JsonObject(); + + object.addProperty("name", source.name()); + + Plugin plugin = Bukkit.getServer().getPluginManager().getPlugin(source.name()); + if (plugin != null) { + object.addProperty("version", plugin.getDescription().getVersion()); + } else { + try { + plugin = JavaPlugin.getProvidingPlugin(source.source()); + object.addProperty("version", plugin.getDescription().getVersion()); + } catch (Exception ex) { + object.add("version", null); + } + } + + return object; + } + /** * Generates the json documentation for this addon at the specified path. * @@ -494,25 +513,6 @@ public void generate(@NotNull Path path) throws IOException { } } - /** - * Gets the json object representing the addon. - * - * @return The json object representing the addon. - */ - private JsonObject getSource() { - JsonObject object = new JsonObject(); - - object.addProperty("name", source.name()); - try { - JavaPlugin plugin = JavaPlugin.getProvidingPlugin(source.source()); - object.addProperty("version", plugin.getDescription().getVersion()); - } catch (Exception ex) { - object.add("version", null); - } - - return object; - } - /** * @deprecated Use {@link #generate(Path)} instead. */ From 3ad4791b773b5e581225b38cb8d0f92eb0d4275a Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Fri, 22 Aug 2025 20:49:32 +0200 Subject: [PATCH 12/13] thx bbg burb --- src/main/java/ch/njol/skript/structures/StructEvent.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/main/java/ch/njol/skript/structures/StructEvent.java b/src/main/java/ch/njol/skript/structures/StructEvent.java index a70e589831f..7f5576fda5b 100644 --- a/src/main/java/ch/njol/skript/structures/StructEvent.java +++ b/src/main/java/ch/njol/skript/structures/StructEvent.java @@ -19,16 +19,16 @@ @Description(""" The structure used for listening to events. - Optionally allows specifying whether to listen to events that have been cancelled, - and allows specifying with which priority to listen to events. + Optionally allows specifying whether to listen to events that have been cancelled, \ + and allows specifying with which priority to listen to events. \ Events are called in the following order of priorities. ``` lowest -> low -> normal -> high -> highest -> monitor ``` - Modifying event-values or cancelling events is not supported when using the 'monitor' priority. It should only - be used for monitoring the outcome of an event. + Modifying event-values or cancelling events is not supported when using the 'monitor' priority. \ + It should only be used for monitoring the outcome of an event. """) @Example(""" on load: From 708adcaa053e54351f0edad1f2ac86d7ed187474 Mon Sep 17 00:00:00 2001 From: Efnilite <35348263+Efnilite@users.noreply.github.com> Date: Fri, 29 Aug 2025 21:30:00 +0200 Subject: [PATCH 13/13] Update src/main/java/ch/njol/skript/doc/JSONGenerator.java Co-authored-by: Patrick Miller --- src/main/java/ch/njol/skript/doc/JSONGenerator.java | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java index 9ec96df6605..4e15967ae9b 100644 --- a/src/main/java/ch/njol/skript/doc/JSONGenerator.java +++ b/src/main/java/ch/njol/skript/doc/JSONGenerator.java @@ -470,16 +470,12 @@ private JsonObject getSource() { object.addProperty("name", source.name()); Plugin plugin = Bukkit.getServer().getPluginManager().getPlugin(source.name()); - if (plugin != null) { - object.addProperty("version", plugin.getDescription().getVersion()); - } else { + if (plugin == null) { try { plugin = JavaPlugin.getProvidingPlugin(source.source()); - object.addProperty("version", plugin.getDescription().getVersion()); - } catch (Exception ex) { - object.add("version", null); - } + } catch (Exception ignored) { } } + object.addProperty("version", plugin == null ? null : plugin.getDescription().getVersion()); return object; }