Merge pull request #443 from PlaceholderAPI/feature/update-documentation

Update Javadoc documentation
This commit is contained in:
PiggyPiglet 2021-01-29 10:10:12 +08:00 committed by GitHub
commit dd2981b13e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 162 additions and 24 deletions

View File

@ -141,10 +141,26 @@ public final class PlaceholderAPI {
.collect(Collectors.toList()); .collect(Collectors.toList());
} }
/**
* Translates all placeholders into their corresponding values.
* <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
*
* @param player Player to parse the placeholders against
* @param text Text to set the placeholder values in
* @return String containing all translated placeholders
*/
public static String setBracketPlaceholders(Player player, String text) { public static String setBracketPlaceholders(Player player, String text) {
return setBracketPlaceholders((OfflinePlayer) player, text); return setBracketPlaceholders((OfflinePlayer) player, text);
} }
/**
* Translates all placeholders into their corresponding values.
* <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
*
* @param player Player to parse the placeholders against
* @param text List of Strings to set the placeholder values in
* @return String containing all translated placeholders
*/
public static List<String> setBracketPlaceholders(Player player, List<String> text) { public static List<String> setBracketPlaceholders(Player player, List<String> text) {
return setPlaceholders((OfflinePlayer) player, text); return setPlaceholders((OfflinePlayer) player, text);
} }
@ -216,7 +232,7 @@ public final class PlaceholderAPI {
/** /**
* Get all registered placeholder identifiers * Get all registered placeholder identifiers
* *
* @return All registered placeholder identifiers * @return A Set of type String containing the identifiers of all registered expansions.
*/ */
@NotNull @NotNull
public static Set<String> getRegisteredIdentifiers() { public static Set<String> getRegisteredIdentifiers() {
@ -227,7 +243,7 @@ public final class PlaceholderAPI {
/** /**
* Get the normal placeholder pattern. * Get the normal placeholder pattern.
* *
* @return The default Placeholder Pattern * @return Regex Pattern of {@literal [%]([^%]+)[%]}
*/ */
public static Pattern getPlaceholderPattern() { public static Pattern getPlaceholderPattern() {
return PLACEHOLDER_PATTERN; return PLACEHOLDER_PATTERN;
@ -236,7 +252,7 @@ public final class PlaceholderAPI {
/** /**
* Get the bracket placeholder pattern. * Get the bracket placeholder pattern.
* *
* @return the Bracket Placeholder Pattern * @return Regex Pattern of {@literal [{]([^{}]+)[}]}
*/ */
public static Pattern getBracketPlaceholderPattern() { public static Pattern getBracketPlaceholderPattern() {
return BRACKET_PLACEHOLDER_PATTERN; return BRACKET_PLACEHOLDER_PATTERN;
@ -245,7 +261,7 @@ public final class PlaceholderAPI {
/** /**
* Get the relational placeholder pattern. * Get the relational placeholder pattern.
* *
* @return The Relational Placeholder Pattern * @return Regex Pattern of {@literal [%](rel_)([^%]+)[%]}
*/ */
public static Pattern getRelationalPlaceholderPattern() { public static Pattern getRelationalPlaceholderPattern() {
return RELATIONAL_PLACEHOLDER_PATTERN; return RELATIONAL_PLACEHOLDER_PATTERN;

View File

@ -26,6 +26,10 @@ import org.bukkit.event.Event;
import org.bukkit.event.HandlerList; import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/**
* Indicates that a {@link PlaceholderExpansion} has been registered by
* PlaceholderAPI.
*/
public final class ExpansionRegisterEvent extends Event implements Cancellable { public final class ExpansionRegisterEvent extends Event implements Cancellable {
@NotNull @NotNull
@ -43,6 +47,11 @@ public final class ExpansionRegisterEvent extends Event implements Cancellable {
return HANDLERS; return HANDLERS;
} }
/**
* The {@link PlaceholderExpansion expansion} that was registered.
*
* @return The {@link PlaceholderExpansion} instance.
*/
@NotNull @NotNull
public PlaceholderExpansion getExpansion() { public PlaceholderExpansion getExpansion() {
return expansion; return expansion;

View File

@ -25,6 +25,10 @@ import org.bukkit.event.Event;
import org.bukkit.event.HandlerList; import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/**
* Indicates that a {@link PlaceholderExpansion} had been unregistered by
* PlaceholderAPI.
*/
public final class ExpansionUnregisterEvent extends Event { public final class ExpansionUnregisterEvent extends Event {
@NotNull @NotNull
@ -43,6 +47,11 @@ public final class ExpansionUnregisterEvent extends Event {
return HANDLERS; return HANDLERS;
} }
/**
* The {@link PlaceholderExpansion expansion} that was unregistered.
*
* @return The {@link PlaceholderExpansion} instance.
*/
@NotNull @NotNull
public PlaceholderExpansion getExpansion() { public PlaceholderExpansion getExpansion() {
return expansion; return expansion;

View File

@ -26,7 +26,10 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/** /**
* This event is called when all expansions are loaded (when reloading config, on plugin start and on server load). * Indicates that <b>all</b> {@link PlaceholderExpansions} have been
* loaded.
* <br/>This event is fired on Server load and when reloading the
* confiuration.
*/ */
public class ExpansionsLoadedEvent extends Event { public class ExpansionsLoadedEvent extends Event {

View File

@ -24,7 +24,7 @@ import java.util.Map;
/** /**
* Any {@link PlaceholderExpansion} class which implements configurable will have any options listed * Any {@link PlaceholderExpansion} class which implements configurable will have any options listed
* in the getDefaults map automatically added to the PlaceholderAPI config.yml file * in the {@link #getDefaults()} map automatically added to the PlaceholderAPI config.yml file
* *
* @author Ryan McCarthy * @author Ryan McCarthy
*/ */

View File

@ -32,10 +32,17 @@ import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable; import org.jetbrains.annotations.Nullable;
/**
* Any class extending this will be able to get registered as a PlaceholderExpansion.
* <br>The registration either happens automatically when the jar file containing a
* class extending this one is located under the {@code PlaceholderAPI/expansions}
* directory or when the {@link #register()} method is called by said class.
*/
public abstract class PlaceholderExpansion extends PlaceholderHook { public abstract class PlaceholderExpansion extends PlaceholderHook {
/** /**
* The placeholder identifier of this expansion * The placeholder identifier of this expansion. May not contain {@literal %},
* {@literal {}} or _
* *
* @return placeholder identifier that is associated with this expansion * @return placeholder identifier that is associated with this expansion
*/ */
@ -154,17 +161,39 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
// === Configuration === // === Configuration ===
/**
* Gets the ConfigurationSection of the expansion located in the config.yml of PlaceholderAPI or
* null when not specified.
* <br>You may use the {@link Configurable} interface to define default values set
*
* @return ConfigurationSection that this epxpansion has.
*/
@Nullable @Nullable
public final ConfigurationSection getConfigSection() { public final ConfigurationSection getConfigSection() {
return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier()); return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier());
} }
/**
* Gets the ConfigurationSection relative to the {@link #getConfigSection() default one} set
* by the expansion or null when the default ConfigurationSection is null
*
* @param path The path to get the ConfigurationSection from. This is relative to the default section
* @return ConfigurationSection relative to the default section
*/
@Nullable @Nullable
public final ConfigurationSection getConfigSection(@NotNull final String path) { public final ConfigurationSection getConfigSection(@NotNull final String path) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? null : section.getConfigurationSection(path); return section == null ? null : section.getConfigurationSection(path);
} }
/**
* Gets the Object relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the provided Default Object, when the default ConfigurationSection is null
*
* @param path The path to get the Object from. This is relative to the default section
* @param def The default Object to return when the ConfigurationSection returns null
* @return Object from the provided path or the default one provided
*/
@Nullable @Nullable
@Contract("_, !null -> !null") @Contract("_, !null -> !null")
public final Object get(@NotNull final String path, final Object def) { public final Object get(@NotNull final String path, final Object def) {
@ -172,21 +201,53 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
return section == null ? def : section.get(path, def); return section == null ? def : section.get(path, def);
} }
/**
* Gets the int relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the provided Default int, when the default ConfigurationSection is null
*
* @param path The path to get the int from. This is relative to the default section
* @param def The default int to return when the ConfigurationSection returns null
* @return int from the provided path or the default one provided
*/
public final int getInt(@NotNull final String path, final int def) { public final int getInt(@NotNull final String path, final int def) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? def : section.getInt(path, def); return section == null ? def : section.getInt(path, def);
} }
/**
* Gets the long relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the provided Default long, when the default ConfigurationSection is null
*
* @param path The path to get the long from. This is relative to the default section
* @param def The default long to return when the ConfigurationSection returns null
* @return long from the provided path or the default one provided
*/
public final long getLong(@NotNull final String path, final long def) { public final long getLong(@NotNull final String path, final long def) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? def : section.getLong(path, def); return section == null ? def : section.getLong(path, def);
} }
/**
* Gets the double relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the provided Default double, when the default ConfigurationSection is null
*
* @param path The path to get the double from. This is relative to the default section
* @param def The default double to return when the ConfigurationSection returns null
* @return double from the provided path or the default one provided
*/
public final double getDouble(@NotNull final String path, final double def) { public final double getDouble(@NotNull final String path, final double def) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? def : section.getDouble(path, def); return section == null ? def : section.getDouble(path, def);
} }
/**
* Gets the String relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the provided Default String, when the default ConfigurationSection is null
*
* @param path The path to get the String from. This is relative to the default section
* @param def The default String to return when the ConfigurationSection returns null. Can be null
* @return String from the provided path or the default one provided
*/
@Nullable @Nullable
@Contract("_, !null -> !null") @Contract("_, !null -> !null")
public final String getString(@NotNull final String path, @Nullable final String def) { public final String getString(@NotNull final String path, @Nullable final String def) {
@ -194,23 +255,58 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
return section == null ? def : section.getString(path, def); return section == null ? def : section.getString(path, def);
} }
/**
* Gets a String List relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or an empty List, when the default ConfigurationSection is null
*
* @param path The path to get the String list from. This is relative to the default section
* @return String list from the provided path or an empty list
*/
@NotNull @NotNull
public final List<String> getStringList(@NotNull final String path) { public final List<String> getStringList(@NotNull final String path) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? Collections.emptyList() : section.getStringList(path); return section == null ? Collections.emptyList() : section.getStringList(path);
} }
/**
* Gets the boolean relative to the {@link #getConfigSection() default ConfigurationSection} set
* by the expansion or the default boolean, when the default ConfigurationSection is null
*
* @param path The path to get the boolean from. This is relative to the default section
* @param def The default boolean to return when the ConfigurationSection is null
* @return boolean from the provided path or the default one provided
*/
@NotNull @NotNull
public final boolean getBoolean(@NotNull final String path, final boolean def) { public final boolean getBoolean(@NotNull final String path, final boolean def) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section == null ? def : section.getBoolean(path, def); return section == null ? def : section.getBoolean(path, def);
} }
/**
* Whether the {@link #getConfigSection() default ConfigurationSection} contains the provided path
* or not. This will return {@code false} when either the default section is null, or doesn't
* contain the provided path
*
* @param path The path to check
* @return true when the default ConfigurationSection is not null and contains the path, false otherwise
*/
public final boolean configurationContains(@NotNull final String path) { public final boolean configurationContains(@NotNull final String path) {
final ConfigurationSection section = getConfigSection(); final ConfigurationSection section = getConfigSection();
return section != null && section.contains(path); return section != null && section.contains(path);
} }
/**
* Whether the provided Object is an instance of this PlaceholderExpansion.
* <br>This method will perform the following checks in order:
* <br><ul>
* <li>Checks if Object equals the class. Returns true when equal and continues otherwise</li>
* <li>Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not</li>
* <li>Checks if the Object's Identifier, Author and version equal the one of this class</li>
* </ul>
*
* @param o The Object to check
* @return true or false depending on the above mentioned checks
*/
@Override @Override
public final boolean equals(final Object o) { public final boolean equals(final Object o) {
if (this == o) { if (this == o) {
@ -227,6 +323,11 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
getVersion().equals(expansion.getVersion()); getVersion().equals(expansion.getVersion());
} }
/**
* Returns a String containing the Expansion's name, author and version
*
* @return String containing name, author and version of the expansion
*/
@Override @Override
public final String toString() { public final String toString() {
return String.format("PlaceholderExpansion[name: '%s', author: '%s', version: '%s']", getName(), return String.format("PlaceholderExpansion[name: '%s', author: '%s', version: '%s']", getName(),