From 2d194af704fb2fd00dd9dd342ae43188c5ac3fe9 Mon Sep 17 00:00:00 2001 From: Stijn Bannink Date: Fri, 10 Nov 2023 11:49:47 +0100 Subject: [PATCH] Added javadoc / API info --- .run/ShowControl build.run.xml | 32 +++++++ .run/ShowControl deploy.run.xml | 32 +++++++ .run/ShowControl javadoc.run.xml | 32 +++++++ pom.xml | 19 ++++ .../sbdevelopment/showcontrol/api/SCAPI.java | 91 ++++++++++++++++++- .../exceptions/InvalidArgumentException.java | 3 + .../exceptions/InvalidTriggerException.java | 3 + .../exceptions/TooFewArgumentsException.java | 3 + .../api/exceptions/package-info.java | 4 + .../showcontrol/api/package-info.java | 4 + .../showcontrol/api/points/ShowCuePoint.java | 11 +++ .../showcontrol/api/points/package-info.java | 4 + .../showcontrol/api/triggers/Trigger.java | 6 ++ .../api/triggers/TriggerIdentifier.java | 23 +++++ .../api/triggers/package-info.java | 4 + 15 files changed, 269 insertions(+), 2 deletions(-) create mode 100644 .run/ShowControl build.run.xml create mode 100644 .run/ShowControl deploy.run.xml create mode 100644 .run/ShowControl javadoc.run.xml create mode 100644 src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/package-info.java create mode 100644 src/main/java/tech/sbdevelopment/showcontrol/api/package-info.java create mode 100644 src/main/java/tech/sbdevelopment/showcontrol/api/points/package-info.java create mode 100644 src/main/java/tech/sbdevelopment/showcontrol/api/triggers/package-info.java diff --git a/.run/ShowControl build.run.xml b/.run/ShowControl build.run.xml new file mode 100644 index 0000000..48d8db0 --- /dev/null +++ b/.run/ShowControl build.run.xml @@ -0,0 +1,32 @@ + + + + + + + + \ No newline at end of file diff --git a/.run/ShowControl deploy.run.xml b/.run/ShowControl deploy.run.xml new file mode 100644 index 0000000..2f5d287 --- /dev/null +++ b/.run/ShowControl deploy.run.xml @@ -0,0 +1,32 @@ + + + + + + + + \ No newline at end of file diff --git a/.run/ShowControl javadoc.run.xml b/.run/ShowControl javadoc.run.xml new file mode 100644 index 0000000..bedb28f --- /dev/null +++ b/.run/ShowControl javadoc.run.xml @@ -0,0 +1,32 @@ + + + + + + + + \ No newline at end of file diff --git a/pom.xml b/pom.xml index 2b15c22..eb2b773 100644 --- a/pom.xml +++ b/pom.xml @@ -23,6 +23,13 @@ + + + sbdevelopment-repo + https://repo.sbdevelopment.tech/releases + + + clean package ${project.name} v${project.version} @@ -85,6 +92,18 @@ + + org.apache.maven.plugins + maven-javadoc-plugin + 3.6.0 + + 11 + --no-module-directories + + **/tech/sbdevelopment/showcontrol/api/** + + + diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/SCAPI.java b/src/main/java/tech/sbdevelopment/showcontrol/api/SCAPI.java index edef746..8d1652c 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/SCAPI.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/SCAPI.java @@ -17,6 +17,7 @@ import tech.sbdevelopment.showcontrol.api.triggers.TriggerIdentifier; import tech.sbdevelopment.showcontrol.data.DataStorage; import tech.sbdevelopment.showcontrol.utils.YamlFile; +import javax.annotation.Nullable; import java.io.File; import java.lang.reflect.Constructor; import java.lang.reflect.InvocationTargetException; @@ -25,15 +26,36 @@ import java.util.concurrent.Executors; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; +/** + * This class is the main class of the API. + */ public class SCAPI { + /** + * A map of all default trigger, only used for tab complete. + */ @Getter - private static final Map defaultTriggers = new HashMap<>(); //DO NOT USE, just for tab complete! + private static final Map defaultTriggers = new HashMap<>(); + /** + * A map of all triggers, used for creating new triggers. + */ @Getter private static final Map> triggers = new HashMap<>(); + /** + * A map of all shows with their cue points. + */ @Getter private static final HashMap> showsMap = new HashMap<>(); + /** + * A map of all show timers. + */ private static final HashMap showTimers = new HashMap<>(); + /** + * Index all triggers in a package. Call this method in your onEnable method. + * + * @param clazz The class to use as starting point, usually your main class. + * @param packages The packages to index. + */ public static void index(Class clazz, String... packages) { ShowControlPlugin.getInstance().getLogger().info("Indexing triggers for starting point " + clazz.getSimpleName() + "..."); @@ -62,11 +84,31 @@ public class SCAPI { } } - public static List getTabComplete(String triggerType, Player player, int index, String arg) { + /** + * Get the tab complete for a trigger. + * + * @param triggerType The trigger type. + * @param player The player that wants to add the cue, will be null if it's not a player. + * @param index The current argument index. + * @param arg The current argument. + * @return The tab complete value based on the index and argument. + */ + public static List getTabComplete(String triggerType, @Nullable Player player, int index, String arg) { if (!defaultTriggers.containsKey(triggerType)) return new ArrayList<>(); return defaultTriggers.get(triggerType).getArgumentTabComplete(player, index, arg); } + /** + * Get a trigger from a data string. + * + * @param data The data string. + * @return The trigger. + * @param The trigger type. + * @throws ReflectiveOperationException When the trigger could not be created. + * @throws InvalidTriggerException When the trigger does not exist. + * @throws TooFewArgumentsException When the trigger data does not have enough arguments. + * @throws IllegalArgumentException When the trigger data is invalid. + */ public static T getTrigger(String data) throws ReflectiveOperationException, InvalidTriggerException, TooFewArgumentsException, IllegalArgumentException { String[] dataSplitter = data.split(" "); String[] dataSplitterNew = Arrays.copyOfRange(dataSplitter, 1, dataSplitter.length); @@ -83,11 +125,21 @@ public class SCAPI { return ctor.newInstance(new Object[]{dataSplitterNew}); } + /** + * Create a new show. + * + * @param name The name of the show. + */ public static void create(String name) { showsMap.put(name, new ArrayList<>()); DataStorage.save(); } + /** + * Delete a show. + * + * @param name The name of the show. + */ public static void delete(String name) { showsMap.remove(name); @@ -95,21 +147,46 @@ public class SCAPI { data.delete(); } + /** + * Check if a show exists. + * + * @param name The name of the show. + * @return If the show exists. + */ public static boolean exists(String name) { return showsMap.containsKey(name); } + /** + * Get the points of a show. + * + * @param name The name of the show. + * @return The points of the show. + */ public static List getPoints(String name) { if (!exists(name)) return new ArrayList<>(); return showsMap.get(name); } + /** + * Add a point to a show. + * + * @param name The name of the show. + * @param time The time of the point. + * @param data The data of the point. + */ public static void addPoint(String name, Long time, Trigger data) { if (!exists(name)) return; getPoints(name).add(new ShowCuePoint(time, data)); DataStorage.save(); } + /** + * Remove a point from a show. + * + * @param name The name of the show. + * @param point The point to remove. + */ public static void removePoint(String name, ShowCuePoint point) { if (!exists(name)) return; @@ -122,6 +199,11 @@ public class SCAPI { data.saveFile(); } + /** + * Start a show. + * + * @param name The name of the show. + */ public static void startShow(String name) { if (!exists(name)) return; ScheduledExecutorService showTimer = Executors.newSingleThreadScheduledExecutor(); @@ -131,6 +213,11 @@ public class SCAPI { showTimers.put(name, showTimer); } + /** + * Cancel a show. + * + * @param name The name of the show. + */ public static void cancelShow(String name) { if (!exists(name)) return; if (!showTimers.containsKey(name)) return; diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidArgumentException.java b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidArgumentException.java index dfc9f9e..6c9d86e 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidArgumentException.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidArgumentException.java @@ -2,6 +2,9 @@ package tech.sbdevelopment.showcontrol.api.exceptions; import lombok.experimental.StandardException; +/** + * Thrown when an argument is invalid + */ @StandardException public class InvalidArgumentException extends Exception { } diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidTriggerException.java b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidTriggerException.java index e9b29e1..ea5dde1 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidTriggerException.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/InvalidTriggerException.java @@ -2,6 +2,9 @@ package tech.sbdevelopment.showcontrol.api.exceptions; import lombok.experimental.StandardException; +/** + * Thrown when a trigger is invalid + */ @StandardException public class InvalidTriggerException extends Exception { } diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/TooFewArgumentsException.java b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/TooFewArgumentsException.java index 132e430..0d4bcd0 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/TooFewArgumentsException.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/TooFewArgumentsException.java @@ -2,6 +2,9 @@ package tech.sbdevelopment.showcontrol.api.exceptions; import lombok.experimental.StandardException; +/** + * Thrown when a trigger has too few arguments + */ @StandardException public class TooFewArgumentsException extends Exception { } diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/package-info.java b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/package-info.java new file mode 100644 index 0000000..6160f50 --- /dev/null +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/exceptions/package-info.java @@ -0,0 +1,4 @@ +/** + * This package contains the exceptions thrown by the plugin. + */ +package tech.sbdevelopment.showcontrol.api.exceptions; \ No newline at end of file diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/package-info.java b/src/main/java/tech/sbdevelopment/showcontrol/api/package-info.java new file mode 100644 index 0000000..6ac6ea3 --- /dev/null +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/package-info.java @@ -0,0 +1,4 @@ +/** + * This package contains the API of the ShowControl plugin. + */ +package tech.sbdevelopment.showcontrol.api; \ No newline at end of file diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/points/ShowCuePoint.java b/src/main/java/tech/sbdevelopment/showcontrol/api/points/ShowCuePoint.java index 0cb9c41..0731ed9 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/points/ShowCuePoint.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/points/ShowCuePoint.java @@ -12,8 +12,19 @@ import java.util.UUID; @Getter @AllArgsConstructor public class ShowCuePoint { + /** + * The ID of the cue point + */ private final UUID cueID; + + /** + * The start-time (milliseconds) + */ private final Long time; + + /** + * The data + */ private final Trigger data; /** diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/points/package-info.java b/src/main/java/tech/sbdevelopment/showcontrol/api/points/package-info.java new file mode 100644 index 0000000..db04349 --- /dev/null +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/points/package-info.java @@ -0,0 +1,4 @@ +/** + * This package contains the point API. + */ +package tech.sbdevelopment.showcontrol.api.points; \ No newline at end of file diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/Trigger.java b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/Trigger.java index 704cc5e..5d04f71 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/Trigger.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/Trigger.java @@ -8,10 +8,16 @@ import org.bukkit.entity.Player; import javax.annotation.Nullable; import java.util.List; +/** + * This class is the base class for all triggers + */ @NoArgsConstructor(force = true) @AllArgsConstructor @Getter public abstract class Trigger { + /** + * The datastring of the trigger + */ private final String[] dataString; /** diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/TriggerIdentifier.java b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/TriggerIdentifier.java index 8651a42..d20b228 100644 --- a/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/TriggerIdentifier.java +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/TriggerIdentifier.java @@ -7,14 +7,37 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * This annotation is used to identify a trigger. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface TriggerIdentifier { + /** + * The identifier of the trigger, used in the add command. + * + * @return The identifier of the trigger. + */ String value(); + /** + * The minimum amount of arguments the trigger needs. + * + * @return The minimum amount of arguments the trigger needs. + */ int minArgs() default 0; + /** + * The description of the arguments the trigger needs. + * + * @return The description of the arguments the trigger needs. + */ String argDesc() default ""; + /** + * The item shown in the GUI for a show. + * + * @return The item shown in the GUI for a show. + */ Material item() default Material.NOTE_BLOCK; } diff --git a/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/package-info.java b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/package-info.java new file mode 100644 index 0000000..76ae51e --- /dev/null +++ b/src/main/java/tech/sbdevelopment/showcontrol/api/triggers/package-info.java @@ -0,0 +1,4 @@ +/** + * This package contains the trigger API. + */ +package tech.sbdevelopment.showcontrol.api.triggers; \ No newline at end of file