Skip to content

Commit 86ae20c

Browse files
committed
Updated Javadocs
1 parent e23de63 commit 86ae20c

File tree

11 files changed

+197
-28
lines changed

11 files changed

+197
-28
lines changed

src/main/java/me/despical/commandframework/CommandArguments.java

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,12 @@ public void sendMessage(String message, Object... params) {
229229
commandSender.sendMessage(Message.applyColorFormatter(MessageFormat.format(message, params)));
230230
}
231231

232+
/**
233+
* Sends the specified {@link Message} to command sender associated with this object.
234+
*
235+
* @param message the {@link Message} object to be sent.
236+
* @see #getSender()
237+
*/
232238
public boolean sendMessage(Message message) {
233239
return message.sendMessage(command, this);
234240
}
@@ -310,7 +316,7 @@ public Optional<Player> getPlayer(int index) {
310316
* @return all arguments as a single String object.
311317
* @since 1.3.8
312318
*/
313-
public String concatenateArguments() {
319+
public String concatArguments() {
314320
return String.join(" ", arguments);
315321
}
316322

@@ -327,7 +333,7 @@ public String concatenateArguments() {
327333
* or {@code from} is greater than {@code to}.
328334
* @since 1.3.8
329335
*/
330-
public String concatenateRangeOf(int from, int to) {
336+
public String concatRangeOf(int from, int to) {
331337
return String.join(" ", Arrays.copyOfRange(arguments, from, to));
332338
}
333339

@@ -381,7 +387,7 @@ public boolean isInteger(String string) {
381387
try {
382388
Integer.parseInt(string);
383389
return true;
384-
} catch (NumberFormatException | NullPointerException exception) {
390+
} catch (Exception exception) {
385391
return false;
386392
}
387393
}
@@ -411,11 +417,33 @@ public boolean isFloatingDecimal(String string) {
411417
try {
412418
Double.parseDouble(string);
413419
return true;
414-
} catch (NumberFormatException | NullPointerException exception) {
420+
} catch (Exception exception) {
415421
return false;
416422
}
417423
}
418424

425+
/**
426+
* This method checks if the current command sender has a cooldown on the command that
427+
* is associated with current {@link CommandArguments} object.
428+
*
429+
* <blockquote>For example,
430+
* <pre>{@code
431+
* @Command(name = "test")
432+
* @Cooldown(cooldown = 5)
433+
* public void testCommand(CommandArguments args) {
434+
* if (args.getLength() != 1) {
435+
* // if sender has cooldown, execution will be end here
436+
* args.checkCooldown();
437+
* }
438+
*
439+
* args.sendMessage("Test command successfully executed.");
440+
* }
441+
* }</pre></blockquote>
442+
*
443+
* Note that execution will be stopped if this method returns {@code true}.
444+
*
445+
* @return {@code true} if the sender has a cooldown on this command
446+
*/
419447
public boolean checkCooldown() {
420448
return CommandFramework.instance.getCooldownManager().hasCooldown(this);
421449
}

src/main/java/me/despical/commandframework/CommandFramework.java

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,45 +117,100 @@ public final void unregisterCommands() {
117117
this.registry.unregisterCommands();
118118
}
119119

120+
/**
121+
* Adds a custom parameter to the parameter handler.
122+
*
123+
* <p>This method allows the addition of a custom parameter to the parameter handler by specifying
124+
* a value and a function that converts {@link CommandArguments} to an instance of a type that
125+
* extends {@link A}.
126+
*
127+
* @param <A> the type of the parent class that the custom parameter's type extends
128+
* @param <B> the type of the custom parameter, which extends {@link A}
129+
* @param value the value to call custom parameter using {@linkplain me.despical.commandframework.annotations.Param @Param}, must not be null,
130+
* can be a class name
131+
* @param function a function that takes {@link CommandArguments} and returns an instance of {@link B},
132+
* must not be null
133+
*
134+
* @throws NullPointerException if {@code value} is already added as a custom parameter
135+
*/
120136
public final <A, B extends A> void addCustomParameter(@NotNull String value, @NotNull Function<CommandArguments, B> function) {
121137
this.parameterHandler.addCustomParameter(value, function);
122138
}
123139

140+
/**
141+
* Returns the logger instance of Command Framework. By default, logger is {@code plugin}'s logger.
142+
*
143+
* @return the current logger instance.
144+
* @since 1.4.8
145+
*/
124146
@NotNull
125147
public final Logger getLogger() {
126148
return logger;
127149
}
128150

151+
/**
152+
* Changes default logger
153+
*
154+
* @param logger the non-null new logger instance
155+
* @since 1.4.8
156+
*/
129157
public final void setLogger(@NotNull Logger logger) {
130158
this.logger = logger;
131159
}
132160

161+
/**
162+
* Enables the specified option.
163+
*
164+
* @param option the {@link Option} to be enabled. Must not be {@code null}.
165+
* @throws IllegalArgumentException if the {@code option} is {@code null}.
166+
* @since 1.4.8
167+
*/
133168
public final void enableOption(Option option) {
134169
this.optionManager.enableOption(option);
135170
}
136171

172+
/**
173+
* Enables the specified options.
174+
*
175+
* @param option the {@link Option} to be enabled. Must not be {@code null}.
176+
* @param options the array of {@link Option} to be enabled. Must not be {@code null}.
177+
* @throws IllegalArgumentException if the {@code option} or {@code options} are {@code null}.
178+
* @since 1.4.8
179+
*/
137180
public final void enableOptions(Option option, Option... options) {
138181
this.optionManager.enableOptions(option, options);
139182
}
140183

184+
/**
185+
* Checks whether the specified {@link Option} is enabled.
186+
*
187+
* @param option the {@link Option} to check.
188+
* @return {@code true} if the option is enabled; {@code false} otherwise.
189+
* @throws IllegalArgumentException if {@code option} is {@code null}.
190+
* @since 1.4.8
191+
*/
141192
public final boolean isOptionEnabled(Option option) {
142193
return this.optionManager.isEnabled(option);
143194
}
144195

196+
@ApiStatus.Internal
145197
final CooldownManager getCooldownManager() {
146198
if (this.cooldownManager == null)
147199
this.cooldownManager = new CooldownManager(this);
148200
return cooldownManager;
149201
}
150202

203+
@ApiStatus.Internal
151204
final CommandRegistry getRegistry() {
152205
return registry;
153206
}
154207

208+
@ApiStatus.Internal
155209
final ParameterHandler getParameterHandler() {
156210
return parameterHandler;
157211
}
158212

213+
@ApiStatus.Internal
159214
final boolean checkConfirmation(CommandSender sender, final Command command, final Method method) {
160215
if (!isOptionEnabled(Option.CONFIRMATIONS)) return false;
161216

src/main/java/me/despical/commandframework/CommandHandler.java

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import org.bukkit.command.TabCompleter;
1111
import org.bukkit.entity.Player;
1212
import org.bukkit.plugin.Plugin;
13+
import org.jetbrains.annotations.ApiStatus;
1314
import org.jetbrains.annotations.NotNull;
1415

1516
import java.lang.reflect.Method;
@@ -18,16 +19,24 @@
1819
import java.util.Map;
1920

2021
/**
22+
* This class handles the command executions and tab completes.
23+
*
24+
* <p>This is an internal class and should not be instantiated or extended by
25+
* any subclasses.
26+
*
2127
* @author Despical
28+
* @since 1.4.8
2229
* <p>
23-
* Created at 18.07.2024
30+
* Created on 18.07.2024
2431
*/
32+
@ApiStatus.Internal
33+
@ApiStatus.NonExtendable
2534
public abstract class CommandHandler implements CommandExecutor, TabCompleter {
2635

2736
private CommandRegistry registry;
2837
private CommandFramework commandFramework;
2938

30-
public void setRegistry(CommandFramework commandFramework) {
39+
void setRegistry(CommandFramework commandFramework) {
3140
this.commandFramework = commandFramework;
3241
this.registry = commandFramework.getRegistry();
3342
}
@@ -49,7 +58,7 @@ public boolean onCommand(@NotNull CommandSender sender, @NotNull org.bukkit.comm
4958
return true;
5059
}
5160

52-
if ((!permission.isEmpty() && !sender.hasPermission(permission))) {
61+
if (!permission.isEmpty() && !sender.hasPermission(permission)) {
5362
arguments.sendMessage(Message.NO_PERMISSION);
5463
return true;
5564
}

src/main/java/me/despical/commandframework/CommandRegistry.java

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,17 @@
2121
import java.util.stream.Stream;
2222

2323
/**
24+
* This class manages the registry of commands, sub-commands and tab completers
25+
* associated with those commands. It also provides helper methods for matching
26+
* commands and their corresponding tab completers.
27+
*
28+
* <p>This is an internal class and should not be instantiated or extended by
29+
* any subclasses.
30+
*
2431
* @author Despical
32+
* @since 1.4.8
2533
* <p>
26-
* Created at 18.07.2024
34+
* Created on 18.07.2024
2735
*/
2836
@ApiStatus.Internal
2937
public class CommandRegistry {
@@ -60,21 +68,31 @@ public class CommandRegistry {
6068
final Field field = SimplePluginManager.class.getDeclaredField("commandMap");
6169
field.setAccessible(true);
6270

63-
commandMap = (CommandMap) field.get(manager);
71+
this.commandMap = (CommandMap) field.get(manager);
6472
} catch (ReflectiveOperationException exception) {
6573
exception.printStackTrace();
6674
}
6775
}
6876
}
6977

70-
public void setCommandMap(@Nullable CommandMap commandMap) {
78+
/**
79+
* Sets the {@link CommandMap} for this instance.
80+
*
81+
* @param commandMap the {@link CommandMap} to be set. Must be non-null.
82+
*/
83+
public void setCommandMap(@NotNull CommandMap commandMap) {
7184
this.commandMap = commandMap;
7285
}
7386

7487
/**
75-
* Registers commands in given object's class.
88+
* Registers commands from the specified instance's class.
89+
* <p>
90+
* This method scans the class of the provided instance and registers all commands
91+
* defined within that class. The class should contain methods annotated to be recognized
92+
* as commands.
93+
* </p>
7694
*
77-
* @param instance the class instance of given object.
95+
* @param instance the instance of the class from which commands will be registered. Must not be {@code null}.
7896
*/
7997
protected void registerCommands(@NotNull Object instance) {
8098
for (final Method method : instance.getClass().getMethods()) {
@@ -114,12 +132,12 @@ protected void registerCommands(@NotNull Object instance) {
114132
}
115133

116134
/**
117-
* Registers the command with given parameters if there are any.
135+
* This method registers a command along with its associated method and instance.
136+
* When the command is executed, the specified method will be invoked.
118137
*
119-
* @param command the command object of registered command method.
120-
* @param method the command method which will invoked run when the
121-
* command is executed.
122-
* @param instance the class instance of the command method.
138+
* @param command the {@link Command} object representing the command to be registered.
139+
* @param method the {@link Method} object representing the method to be invoked when the command is executed.
140+
* @param instance the instance of the class that contains the command method.
123141
*/
124142
protected void registerCommand(Command command, Method method, Object instance) {
125143
final String cmdName = command.name();
@@ -148,9 +166,10 @@ protected void registerCommand(Command command, Method method, Object instance)
148166
}
149167

150168
/**
151-
* Unregisters command and tab completer if there is with the given name.
169+
* Unregisters a command and its associated tab completer if they are registered with the specified name.
152170
*
153-
* @param commandName name of the command that's going to be removed
171+
* @param commandName the name of the command to be unregistered. Must not be {@code null} or empty.
172+
* @throws IllegalArgumentException if {@code commandName} is {@code null} or an empty string.
154173
*/
155174
protected void unregisterCommand(@NotNull String commandName) {
156175
if (commandName.contains(".")) commandName = commandName.split("\\.")[0];
@@ -189,7 +208,7 @@ protected void unregisterCommand(@NotNull String commandName) {
189208
}
190209

191210
/**
192-
* Unregisters all of registered commands and tab completers created using that instance.
211+
* Unregisters all commands and tab completers that were registered using the instance of this object.
193212
*/
194213
protected void unregisterCommands() {
195214
Iterator<String> names = commands.keySet().stream().map(Command::name).iterator();
@@ -214,6 +233,9 @@ protected CommandMatcher getCommandMatcher() {
214233
return this.commandMatcher;
215234
}
216235

236+
/**
237+
* A helper class that contains methods for matching commands and their corresponding tab completers.
238+
*/
217239
protected final class CommandMatcher {
218240

219241
@Nullable

src/main/java/me/despical/commandframework/Message.java

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import me.despical.commandframework.annotations.Command;
44
import org.bukkit.ChatColor;
5+
import org.jetbrains.annotations.ApiStatus;
56
import org.jetbrains.annotations.NotNull;
67

78
import java.util.function.BiFunction;
@@ -52,15 +53,22 @@ public static void setColorFormatter(@NotNull Function<String, String> colorForm
5253
Message.colorFormatter = colorFormatter;
5354
}
5455

55-
public static String applyColorFormatter(final @NotNull String string) {
56-
return colorFormatter.apply(string);
57-
}
58-
56+
/**
57+
* Set a custom error message.
58+
*
59+
* @param message the custom error message.
60+
*/
5961
public void setMessage(final BiFunction<Command, CommandArguments, Boolean> message) {
6062
this.message = message;
6163
}
6264

63-
public boolean sendMessage(final Command command, final CommandArguments arguments) {
65+
@ApiStatus.Internal
66+
static String applyColorFormatter(final @NotNull String string) {
67+
return colorFormatter.apply(string);
68+
}
69+
70+
@ApiStatus.Internal
71+
boolean sendMessage(final Command command, final CommandArguments arguments) {
6472
return this.message.apply(command, arguments);
6573
}
6674

src/main/java/me/despical/commandframework/annotations/Default.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
* The default value for the parameter annotated with
1717
* {@link Param}, if the value of parameter is null.
1818
*
19-
* @return default value for the possible null parameter
19+
* @return the default value for the possible null parameter
2020
*/
2121
String value();
2222
}

src/main/java/me/despical/commandframework/annotations/Param.java

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,15 @@
1212
@Retention(RetentionPolicy.RUNTIME)
1313
public @interface Param {
1414

15+
/**
16+
* The unique id of the parameter.
17+
* <p>
18+
* If a {@link Class} name is used as an id then no need for
19+
* this annotation to be used. The parameters can directly be
20+
* used from method's parameter list.
21+
* </p>
22+
*
23+
* @return the unique id to call annotated parameter
24+
*/
1525
String value();
1626
}

0 commit comments

Comments
 (0)