Merge pull request #84 from TheNextLvl-net/javadocs

Added Javadocs for command registry and permission overrides

Author: NonSwag

api/src/main/java/net/thenextlvl/commander/CommandRegistry.java

@@ -7,23 +7,91 @@
 
 @NullMarked
 public interface CommandRegistry {
+    /**
+     * Retrieves the set of commands that are currently hidden from visibility.
+     * <p>
+     * Hidden commands are still accessible and executable but are not displayed
+     * in suggestions or tab completions under normal conditions.
+     *
+     * @return an unmodifiable set of strings representing the commands that are currently hidden
+     */
     @Unmodifiable
     Set<String> hiddenCommands();
 
+    /**
+     * Retrieves the set of commands that are currently unregistered in the system.
+     *
+     * @return an unmodifiable set of strings representing the commands that are unregistered
+     */
     @Unmodifiable
     Set<String> unregisteredCommands();
 
+    /**
+     * Hides the specified command.
+     * <p>
+     * Hidden commands can be accessed as normal but are not shown during tab completion.
+     * They remain visible to users who possess the appropriate bypass permission.
+     *
+     * @param command the name of the command to hide
+     * @return true if the command was hidden, false if the command was already hidden or doesn't exist
+     */
     boolean hide(String command);
 
+    /**
+     * Determines if the specified command is currently hidden.
+     *
+     * @param command the name of the command to check
+     * @return true if the command is hidden, false otherwise
+     */
     boolean isHidden(String command);
 
+    /**
+     * Checks if the specified command is currently unregistered.
+     *
+     * @param command the name of the command to check
+     * @return true if the command is unregistered, false otherwise
+     */
     boolean isUnregistered(String command);
 
+    /**
+     * Registers the specified command with the command registry.
+     * <p>
+     * This method attempts to add the given command back into the system's registry,
+     * making it available for usage if it was previously unregistered.
+     *
+     * @param command the name of the command to register
+     * @return true if the command was successfully registered,
+     * false if the command was already registered or failed to register
+     */
     boolean register(String command);
 
+    /**
+     * Reveals the specified command.
+     * <p>
+     * This method makes a previously hidden command visible again for suggestions and tab completions.
+     *
+     * @param command the name of the command to reveal
+     * @return true if the command was successfully revealed,
+     * false if the command was already visible or does not exist
+     */
     boolean reveal(String command);
 
+    /**
+     * Unregisters the specified command from the command registry.
+     * This method removes the command, making it unavailable for usage.
+     *
+     * @param command the name of the command to unregister
+     * @return true if the command was successfully unregistered,
+     * false if the command was already unregistered or does not exist
+     */
     boolean unregister(String command);
 
+    /**
+     * Unregisters all currently registered commands in the command registry.
+     * <p>
+     * This method removes all commands from the registry, making them unavailable for execution
+     * and preventing them from appearing in any suggestions or tab completions.
+     * It is typically used during plugin lifecycle events to reset or clear the command state.
+     */
     void unregisterCommands();
 }

api/src/main/java/net/thenextlvl/commander/PermissionOverride.java

@@ -8,23 +8,84 @@
 
 @NullMarked
 public interface PermissionOverride {
+    /**
+     * Retrieves a mapping of commands and their associated original permissions.
+     * <p>
+     * The map provides a view of commands with the permissions initially assigned
+     * to them before any modifications or overrides were applied.
+     *
+     * @return an unmodifiable map containing command names as keys and their initially assigned permissions as values.
+     * The permission value may be null if no original permission was assigned.
+     */
     @Unmodifiable
     Map<String, @Nullable String> originalPermissions();
 
+    /**
+     * Retrieves a mapping of commands and their associated permission overrides.
+     * <p>
+     * The map provides a view of commands with permissions that have been modified
+     * or overridden from their original values.
+     *
+     * @return an unmodifiable map containing command names as keys and their overridden permissions as values.
+     * The permission value may be null if no override is applied to the command.
+     */
     @Unmodifiable
     Map<String, @Nullable String> overrides();
 
+    /**
+     * Retrieves the original permission assigned to the specified command before any overrides or modifications.
+     *
+     * @param command the name of the command whose original permission is to be retrieved
+     * @return the originally assigned permission as a string, or null if no original permission exists for the command
+     */
     @Nullable
     String originalPermission(String command);
 
+    /**
+     * Retrieves the current effective permission associated with the specified command.
+     * The returned permission reflects any overrides that may have been applied.
+     *
+     * @param command the name of the command for which to retrieve the permission
+     * @return the effective permission as a string, or null if no permission is assigned to the command
+     */
     @Nullable
     String permission(String command);
 
+    /**
+     * Determines if the specified command has its permission overridden.
+     * A command is considered overridden if it has a modified permission that differs from its original assignment.
+     *
+     * @param command the name of the command to check
+     * @return true if the command's permission is overridden, false otherwise
+     */
     boolean isOverridden(String command);
 
+    /**
+     * Overrides the permission associated with a command.
+     * <p>
+     * If the provided permission is null, the method attempts to remove the original permission,
+     * effectively unassigning any existing permission.
+     *
+     * @param command the name of the command whose permission is to be overridden
+     * @param permission the new permission to assign to the command, or null to remove
+     * @return true if the operation was successful, false otherwise
+     */
     boolean override(String command, @Nullable String permission);
 
+    /**
+     * Reverts the permission of the given command to its original state before any overrides were applied.
+     *
+     * @param command the name of the command whose permission is to be reset
+     * @return true if the permission override was successfully reset, false otherwise
+     */
     boolean reset(String command);
 
+    /**
+     * Applies permission overrides to all commands.
+     * <p>
+     * This method enforces the overridden permissions configured in the system,
+     * replacing the original permissions for all applicable commands.
+     * Any subsequent retrieval of permissions will reflect the overridden values.
+     */
     void overridePermissions();
 }