From 75e6a3da79c2911720d4f10bf06ab204bb2fe30b Mon Sep 17 00:00:00 2001 From: Auxilor Date: Mon, 13 Dec 2021 09:54:39 +0000 Subject: [PATCH] Documentation and visibility changes --- .../com/willfp/eco/core/PluginDependent.java | 7 ++ .../willfp/eco/core/command/CommandBase.java | 80 ++++++++++--------- .../eco/core/command/CommandHandler.java | 2 +- .../eco/core/command/TabCompleteHandler.java | 2 +- .../eco/core/command/impl/PluginCommand.java | 4 +- .../willfp/eco/core/config/ConfigType.java | 2 +- .../eco/core/config/TransientConfig.java | 4 +- .../config/interfaces/LoadableConfig.java | 7 ++ .../core/config/wrapper/ConfigWrapper.java | 6 +- 9 files changed, 69 insertions(+), 45 deletions(-) diff --git a/eco-api/src/main/java/com/willfp/eco/core/PluginDependent.java b/eco-api/src/main/java/com/willfp/eco/core/PluginDependent.java index 7599ff74..b20788d2 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/PluginDependent.java +++ b/eco-api/src/main/java/com/willfp/eco/core/PluginDependent.java @@ -4,6 +4,13 @@ import org.jetbrains.annotations.NotNull; /** * Quick DI class to manage passing eco plugins. + *

+ * Basically just a quick bit of laziness if you can't be bothered to add a private field + * and a protected getter, don't use this in kotlin as you can just specify + * {@code + * private val plugin: EcoPlugin + * } + * in the constructor. * * @param The eco plugin type. */ diff --git a/eco-api/src/main/java/com/willfp/eco/core/command/CommandBase.java b/eco-api/src/main/java/com/willfp/eco/core/command/CommandBase.java index cd86e395..4a3af9ee 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/command/CommandBase.java +++ b/eco-api/src/main/java/com/willfp/eco/core/command/CommandBase.java @@ -39,44 +39,10 @@ public interface CommandBase { */ CommandBase addSubcommand(@NotNull CommandBase command); - /** - * Get the handler. - * - * @return The handler. - * @deprecated Use {@link CommandBase#onExecute(CommandSender, List)} instead. - */ - @Deprecated - CommandHandler getHandler(); - - /** - * Set the handler. - * - * @param handler The handler. - * @deprecated Handlers have been deprecated. - */ - @Deprecated - void setHandler(@NotNull CommandHandler handler); - - /** - * Get the tab completer. - * - * @return The tab completer. - * @deprecated Use {@link CommandBase#tabComplete(CommandSender, List)} instead. - */ - @Deprecated - TabCompleteHandler getTabCompleter(); - - /** - * Set the tab completer. - * - * @param handler The handler. - * @deprecated Handlers have been deprecated. - */ - @Deprecated - void setTabCompleter(@NotNull TabCompleteHandler handler); - /** * Handle command execution. + *

+ * Marked as default void with no implementation for backwards compatibility. * * @param sender The sender. * @param args The args. @@ -88,6 +54,8 @@ public interface CommandBase { /** * Handle tab completion. + *

+ * Marked as default void with no implementation for backwards compatibility. * * @param sender The sender. * @param args The args. @@ -97,4 +65,44 @@ public interface CommandBase { @NotNull List args) { return new ArrayList<>(); } + + /** + * Get the handler. + * + * @return The handler. + * @see CommandHandler + * @deprecated Use {@link CommandBase#onExecute(CommandSender, List)} instead. + */ + @Deprecated + CommandHandler getHandler(); + + /** + * Set the handler. + * + * @param handler The handler. + * @see CommandHandler + * @deprecated Handlers have been deprecated. + */ + @Deprecated + void setHandler(@NotNull CommandHandler handler); + + /** + * Get the tab completer. + * + * @return The tab completer. + * @see TabCompleteHandler + * @deprecated Use {@link CommandBase#tabComplete(CommandSender, List)} instead. + */ + @Deprecated + TabCompleteHandler getTabCompleter(); + + /** + * Set the tab completer. + * + * @param handler The handler. + * @see TabCompleteHandler + * @deprecated Handlers have been deprecated. + */ + @Deprecated + void setTabCompleter(@NotNull TabCompleteHandler handler); } diff --git a/eco-api/src/main/java/com/willfp/eco/core/command/CommandHandler.java b/eco-api/src/main/java/com/willfp/eco/core/command/CommandHandler.java index d1ddf2fb..6b28a91c 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/command/CommandHandler.java +++ b/eco-api/src/main/java/com/willfp/eco/core/command/CommandHandler.java @@ -13,7 +13,7 @@ import java.util.List; * * @see CommandBase * @deprecated Handlers have been deprecated. This legacy system will eventually be removed, - * update to use the new system. + * update to use the new system: {@link CommandBase#onExecute(CommandSender, List)}. */ @FunctionalInterface @Deprecated(since = "6.17.0") diff --git a/eco-api/src/main/java/com/willfp/eco/core/command/TabCompleteHandler.java b/eco-api/src/main/java/com/willfp/eco/core/command/TabCompleteHandler.java index 3716c57b..85bcbbe9 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/command/TabCompleteHandler.java +++ b/eco-api/src/main/java/com/willfp/eco/core/command/TabCompleteHandler.java @@ -13,7 +13,7 @@ import java.util.List; * * @see CommandBase * @deprecated Handlers have been deprecated. This legacy system will eventually be removed, - * update to use the new system. + * update to use the new system: {@link CommandBase#tabComplete(CommandSender, List)} */ @FunctionalInterface @Deprecated(since = "6.17.0") diff --git a/eco-api/src/main/java/com/willfp/eco/core/command/impl/PluginCommand.java b/eco-api/src/main/java/com/willfp/eco/core/command/impl/PluginCommand.java index 9c88714f..43f818a4 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/command/impl/PluginCommand.java +++ b/eco-api/src/main/java/com/willfp/eco/core/command/impl/PluginCommand.java @@ -12,7 +12,9 @@ import org.jetbrains.annotations.Nullable; import java.util.List; /** - * PluginCommands are the class to be used instead of CommandExecutor. + * PluginCommands are the class to be used instead of CommandExecutor, + * they function as the base command, e.g. {@code /ecoenchants} would be a base command, with each + * subsequent argument functioning as subcommands. *

* The command will not be registered until register() is called. *

diff --git a/eco-api/src/main/java/com/willfp/eco/core/config/ConfigType.java b/eco-api/src/main/java/com/willfp/eco/core/config/ConfigType.java index ce4c8f7d..2721144e 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/config/ConfigType.java +++ b/eco-api/src/main/java/com/willfp/eco/core/config/ConfigType.java @@ -1,7 +1,7 @@ package com.willfp.eco.core.config; /** - * Config types. + * Config types, classified by file extension. */ public enum ConfigType { /** diff --git a/eco-api/src/main/java/com/willfp/eco/core/config/TransientConfig.java b/eco-api/src/main/java/com/willfp/eco/core/config/TransientConfig.java index f6074696..dc11610b 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/config/TransientConfig.java +++ b/eco-api/src/main/java/com/willfp/eco/core/config/TransientConfig.java @@ -9,9 +9,9 @@ import org.jetbrains.annotations.NotNull; import java.util.Map; /** - * Config implementation for passing YamlConfigurations. + * Config that exists purely in the code, not linked to any file. *

- * Does not automatically update. + * Use for inline configs to move data around or to add subsections to other configs. */ public class TransientConfig extends ConfigWrapper { /** diff --git a/eco-api/src/main/java/com/willfp/eco/core/config/interfaces/LoadableConfig.java b/eco-api/src/main/java/com/willfp/eco/core/config/interfaces/LoadableConfig.java index 8eb67140..bb2aad58 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/config/interfaces/LoadableConfig.java +++ b/eco-api/src/main/java/com/willfp/eco/core/config/interfaces/LoadableConfig.java @@ -1,6 +1,7 @@ package com.willfp.eco.core.config.interfaces; import org.bukkit.configuration.file.YamlConfiguration; +import org.bukkit.plugin.java.JavaPlugin; import org.jetbrains.annotations.Nullable; import java.io.File; @@ -45,6 +46,12 @@ public interface LoadableConfig extends Config { /** * Get bukkit {@link YamlConfiguration}. + *

+ * This method is not recommended unless absolutely required as it + * only returns true if {@link this#getType()} is {@link com.willfp.eco.core.config.ConfigType#YAML}, + * and if the handle is an {@link YamlConfiguration} specifically. This depends on the internals + * and the implementation, and so may cause problems - it exists mostly for parity with + * {@link JavaPlugin#getConfig()}. * * @return The config, or null if config is not yaml-based. */ diff --git a/eco-api/src/main/java/com/willfp/eco/core/config/wrapper/ConfigWrapper.java b/eco-api/src/main/java/com/willfp/eco/core/config/wrapper/ConfigWrapper.java index 5994968f..d73895c0 100644 --- a/eco-api/src/main/java/com/willfp/eco/core/config/wrapper/ConfigWrapper.java +++ b/eco-api/src/main/java/com/willfp/eco/core/config/wrapper/ConfigWrapper.java @@ -3,7 +3,6 @@ package com.willfp.eco.core.config.wrapper; import com.willfp.eco.core.config.ConfigType; import com.willfp.eco.core.config.interfaces.Config; import com.willfp.eco.util.StringUtils; -import org.bukkit.configuration.file.YamlConfiguration; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; @@ -17,7 +16,8 @@ import java.util.List; * * @param The type of the handle. */ -public abstract class ConfigWrapper implements Config { +@SuppressWarnings("MethodDoesntCallSuperMethod") +public class ConfigWrapper implements Config { /** * Configs from eco have an internal implementation, * which is the handle. @@ -35,7 +35,7 @@ public abstract class ConfigWrapper implements Config { * * @param handle The config that is being wrapped. */ - protected ConfigWrapper(@NotNull final T handle) { + public ConfigWrapper(@NotNull final T handle) { this.handle = handle; }