13
0
geforkt von Mirrors/Paper

#881: Update Scoreboard Javadocs, remove explicit exception throwing

By: Parker Hawke <hawkeboyz2@hotmail.com>
Dieser Commit ist enthalten in:
Bukkit/Spigot 2023-07-16 15:21:54 +10:00
Ursprung 4e61eca624
Commit eddd72e50b
5 geänderte Dateien mit 63 neuen und 126 gelöschten Zeilen

Datei anzeigen

@ -234,9 +234,7 @@ public interface Criteria {
*
* @param statistic the statistic for which to get a criteria
* @param material the relevant material
*
* @return the criteria
*
* @throws IllegalArgumentException if {@link Statistic#getType()} is anything other than
* {@link Type#BLOCK} or {@link Type#ITEM}
* @throws IllegalArgumentException if {@link Statistic#getType()} is {@link Type#BLOCK}, but
@ -298,9 +296,7 @@ public interface Criteria {
*
* @param statistic the statistic for which to get a criteria
* @param entityType the relevant entity type
*
* @return the criteria
*
* @throws IllegalArgumentException if {@link Statistic#getType()} is not {@link Type#ENTITY}
*/
@NotNull
@ -334,7 +330,6 @@ public interface Criteria {
* and for entity-related statistics, see {@link #statistic(Statistic, EntityType)}
*
* @param statistic the statistic for which to get a criteria
*
* @return the criteria
*/
@NotNull
@ -347,7 +342,6 @@ public interface Criteria {
* Get (or create) a new {@link Criteria} by its name.
*
* @param name the criteria name
*
* @return the created criteria
*/
@NotNull

Datei anzeigen

@ -18,7 +18,7 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
*/
@NotNull
String getName() throws IllegalStateException;
String getName();
/**
* Gets the name displayed to players for this objective
@ -27,18 +27,15 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
*/
@NotNull
String getDisplayName() throws IllegalStateException;
String getDisplayName();
/**
* Sets the name displayed to players for this objective.
*
* @param displayName Display name to set
* @throws IllegalStateException if this objective has been unregistered
* @throws IllegalArgumentException if displayName is null
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
*/
void setDisplayName(@NotNull String displayName) throws IllegalStateException, IllegalArgumentException;
void setDisplayName(@NotNull String displayName);
/**
* Gets the criteria this objective tracks.
@ -49,7 +46,7 @@ public interface Objective {
*/
@Deprecated
@NotNull
String getCriteria() throws IllegalStateException;
String getCriteria();
/**
* Gets the criteria this objective tracks.
@ -58,7 +55,7 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
*/
@NotNull
Criteria getTrackedCriteria() throws IllegalStateException;
Criteria getTrackedCriteria();
/**
* Gets if the objective's scores can be modified directly by a plugin.
@ -67,7 +64,7 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
* @see Criterias#HEALTH
*/
boolean isModifiable() throws IllegalStateException;
boolean isModifiable();
/**
* Gets the scoreboard to which this objective is attached.
@ -83,7 +80,7 @@ public interface Objective {
*
* @throws IllegalStateException if this objective has been unregistered
*/
void unregister() throws IllegalStateException;
void unregister();
/**
* Sets this objective to display on the specified slot for the
@ -92,7 +89,7 @@ public interface Objective {
* @param slot display slot to change, or null to not display
* @throws IllegalStateException if this objective has been unregistered
*/
void setDisplaySlot(@Nullable DisplaySlot slot) throws IllegalStateException;
void setDisplaySlot(@Nullable DisplaySlot slot);
/**
* Gets the display slot this objective is displayed at.
@ -101,7 +98,7 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
*/
@Nullable
DisplaySlot getDisplaySlot() throws IllegalStateException;
DisplaySlot getDisplaySlot();
/**
* Sets manner in which this objective will be rendered.
@ -109,7 +106,7 @@ public interface Objective {
* @param renderType new render type
* @throws IllegalStateException if this objective has been unregistered
*/
void setRenderType(@NotNull RenderType renderType) throws IllegalStateException;
void setRenderType(@NotNull RenderType renderType);
/**
* Sets manner in which this objective will be rendered.
@ -118,31 +115,29 @@ public interface Objective {
* @throws IllegalStateException if this objective has been unregistered
*/
@NotNull
RenderType getRenderType() throws IllegalStateException;
RenderType getRenderType();
/**
* Gets a player's Score for an Objective on this Scoreboard
*
* @param player Player for the Score
* @return Score tracking the Objective and player specified
* @throws IllegalArgumentException if player is null
* @throws IllegalStateException if this objective has been unregistered
* @see #getScore(String)
* @deprecated Scoreboards can contain entries that aren't players
*/
@Deprecated
@NotNull
Score getScore(@NotNull OfflinePlayer player) throws IllegalArgumentException, IllegalStateException;
Score getScore(@NotNull OfflinePlayer player);
/**
* Gets an entry's Score for an Objective on this Scoreboard.
*
* @param entry Entry for the Score
* @return Score tracking the Objective and entry specified
* @throws IllegalArgumentException if entry is null
* @throws IllegalStateException if this objective has been unregistered
* @throws IllegalArgumentException if entry is longer than 32767 characters.
*/
@NotNull
Score getScore(@NotNull String entry) throws IllegalArgumentException, IllegalStateException;
Score getScore(@NotNull String entry);
}

Datei anzeigen

@ -45,7 +45,7 @@ public interface Score {
* @throws IllegalStateException if the associated objective has been
* unregistered
*/
int getScore() throws IllegalStateException;
int getScore();
/**
* Sets the current score.
@ -54,7 +54,7 @@ public interface Score {
* @throws IllegalStateException if the associated objective has been
* unregistered
*/
void setScore(int score) throws IllegalStateException;
void setScore(int score);
/**
* Shows if this score has been set at any point in time.
@ -63,7 +63,7 @@ public interface Score {
* @throws IllegalStateException if the associated objective has been
* unregistered
*/
boolean isScoreSet() throws IllegalStateException;
boolean isScoreSet();
/**
* Gets the scoreboard for the associated objective.

Datei anzeigen

@ -16,17 +16,15 @@ public interface Scoreboard {
* @param name Name of the Objective
* @param criteria Criteria for the Objective
* @return The registered Objective
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if name is longer than 32767
* characters.
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if an objective by that name already
* exists
* @deprecated a displayName should be explicitly specified
*/
@Deprecated
@NotNull
Objective registerNewObjective(@NotNull String name, @NotNull String criteria) throws IllegalArgumentException;
Objective registerNewObjective(@NotNull String name, @NotNull String criteria);
/**
* Registers an Objective on this Scoreboard
@ -35,19 +33,14 @@ public interface Scoreboard {
* @param criteria Criteria for the Objective
* @param displayName Name displayed to players for the Objective.
* @return The registered Objective
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if name is longer than 32767
* characters.
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if displayName is null
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
* @throws IllegalArgumentException if an objective by that name already
* exists
* @deprecated use {@link #registerNewObjective(String, Criteria, String)}
*/
@NotNull
Objective registerNewObjective(@NotNull String name, @NotNull String criteria, @NotNull String displayName) throws IllegalArgumentException;
Objective registerNewObjective(@NotNull String name, @NotNull String criteria, @NotNull String displayName);
/**
* Registers an Objective on this Scoreboard
@ -57,20 +50,14 @@ public interface Scoreboard {
* @param displayName Name displayed to players for the Objective.
* @param renderType Manner of rendering the Objective
* @return The registered Objective
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if name is longer than 32767
* characters.
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if displayName is null
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
* @throws IllegalArgumentException if renderType is null
* @throws IllegalArgumentException if an objective by that name already
* exists
* @deprecated use {@link #registerNewObjective(String, Criteria, String, RenderType)}
*/
@NotNull
Objective registerNewObjective(@NotNull String name, @NotNull String criteria, @NotNull String displayName, @NotNull RenderType renderType) throws IllegalArgumentException;
Objective registerNewObjective(@NotNull String name, @NotNull String criteria, @NotNull String displayName, @NotNull RenderType renderType);
/**
* Registers an Objective on this Scoreboard
@ -79,18 +66,13 @@ public interface Scoreboard {
* @param criteria Criteria for the Objective
* @param displayName Name displayed to players for the Objective.
* @return The registered Objective
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if name is longer than 32767
* characters.
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if displayName is null
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
* @throws IllegalArgumentException if an objective by that name already
* exists
*/
@NotNull
Objective registerNewObjective(@NotNull String name, @NotNull Criteria criteria, @NotNull String displayName) throws IllegalArgumentException;
Objective registerNewObjective(@NotNull String name, @NotNull Criteria criteria, @NotNull String displayName);
/**
* Registers an Objective on this Scoreboard
@ -100,51 +82,42 @@ public interface Scoreboard {
* @param displayName Name displayed to players for the Objective.
* @param renderType Manner of rendering the Objective
* @return The registered Objective
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if name is longer than 32767
* characters.
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if displayName is null
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
* @throws IllegalArgumentException if renderType is null
* @throws IllegalArgumentException if an objective by that name already
* exists
*/
@NotNull
Objective registerNewObjective(@NotNull String name, @NotNull Criteria criteria, @NotNull String displayName, @NotNull RenderType renderType) throws IllegalArgumentException;
Objective registerNewObjective(@NotNull String name, @NotNull Criteria criteria, @NotNull String displayName, @NotNull RenderType renderType);
/**
* Gets an Objective on this Scoreboard by name
*
* @param name Name of the Objective
* @return the Objective or null if it does not exist
* @throws IllegalArgumentException if name is null
*/
@Nullable
Objective getObjective(@NotNull String name) throws IllegalArgumentException;
Objective getObjective(@NotNull String name);
/**
* Gets all Objectives of a Criteria on the Scoreboard
*
* @param criteria Criteria to search by
* @return an immutable set of Objectives using the specified Criteria
* @throws IllegalArgumentException if criteria is null
* @deprecated use {@link #getObjectivesByCriteria(Criteria)}
*/
@Deprecated
@NotNull
Set<Objective> getObjectivesByCriteria(@NotNull String criteria) throws IllegalArgumentException;
Set<Objective> getObjectivesByCriteria(@NotNull String criteria);
/**
* Gets all Objectives of a Criteria on the Scoreboard
*
* @param criteria Criteria to search by
* @return an immutable set of Objectives using the specified Criteria
* @throws IllegalArgumentException if criteria is null
*/
@NotNull
Set<Objective> getObjectivesByCriteria(@NotNull Criteria criteria) throws IllegalArgumentException;
Set<Objective> getObjectivesByCriteria(@NotNull Criteria criteria);
/**
* Gets all Objectives on this Scoreboard
@ -161,85 +134,77 @@ public interface Scoreboard {
* @param slot The DisplaySlot
* @return the Objective currently displayed or null if nothing is
* displayed in that DisplaySlot
* @throws IllegalArgumentException if slot is null
*/
@Nullable
Objective getObjective(@NotNull DisplaySlot slot) throws IllegalArgumentException;
Objective getObjective(@NotNull DisplaySlot slot);
/**
* Gets all scores for a player on this Scoreboard
*
* @param player the player whose scores are being retrieved
* @return immutable set of all scores tracked for the player
* @throws IllegalArgumentException if player is null
* @see #getScores(String)
* @deprecated Scoreboards can contain entries that aren't players
*/
@Deprecated
@NotNull
Set<Score> getScores(@NotNull OfflinePlayer player) throws IllegalArgumentException;
Set<Score> getScores(@NotNull OfflinePlayer player);
/**
* Gets all scores for an entry on this Scoreboard
*
* @param entry the entry whose scores are being retrieved
* @return immutable set of all scores tracked for the entry
* @throws IllegalArgumentException if entry is null
*/
@NotNull
Set<Score> getScores(@NotNull String entry) throws IllegalArgumentException;
Set<Score> getScores(@NotNull String entry);
/**
* Removes all scores for a player on this Scoreboard
*
* @param player the player to drop all current scores for
* @throws IllegalArgumentException if player is null
* @see #resetScores(String)
* @deprecated Scoreboards can contain entries that aren't players
*/
@Deprecated
void resetScores(@NotNull OfflinePlayer player) throws IllegalArgumentException;
void resetScores(@NotNull OfflinePlayer player);
/**
* Removes all scores for an entry on this Scoreboard
*
* @param entry the entry to drop all current scores for
* @throws IllegalArgumentException if entry is null
*/
void resetScores(@NotNull String entry) throws IllegalArgumentException;
void resetScores(@NotNull String entry);
/**
* Gets a player's Team on this Scoreboard
*
* @param player the player to search for
* @return the player's Team or null if the player is not on a team
* @throws IllegalArgumentException if player is null
* @see #getEntryTeam(String)
* @deprecated Scoreboards can contain entries that aren't players
*/
@Deprecated
@Nullable
Team getPlayerTeam(@NotNull OfflinePlayer player) throws IllegalArgumentException;
Team getPlayerTeam(@NotNull OfflinePlayer player);
/**
* Gets a entries Team on this Scoreboard
*
* @param entry the entry to search for
* @return the entries Team or null if the entry is not on a team
* @throws IllegalArgumentException if entry is null
*/
@Nullable
Team getEntryTeam(@NotNull String entry) throws IllegalArgumentException;
Team getEntryTeam(@NotNull String entry);
/**
* Gets a Team by name on this Scoreboard
*
* @param teamName Team name
* @return the matching Team or null if no matches
* @throws IllegalArgumentException if teamName is null
*/
@Nullable
Team getTeam(@NotNull String teamName) throws IllegalArgumentException;
Team getTeam(@NotNull String teamName);
/**
* Gets all teams on this Scoreboard
@ -254,11 +219,10 @@ public interface Scoreboard {
*
* @param name Team name
* @return registered Team
* @throws IllegalArgumentException if name is null
* @throws IllegalArgumentException if team by that name already exists
*/
@NotNull
Team registerNewTeam(@NotNull String name) throws IllegalArgumentException;
Team registerNewTeam(@NotNull String name);
/**
* Gets all players tracked by this Scoreboard
@ -283,7 +247,6 @@ public interface Scoreboard {
* Clears any objective in the specified slot.
*
* @param slot the slot to remove objectives
* @throws IllegalArgumentException if slot is null
*/
void clearSlot(@NotNull DisplaySlot slot) throws IllegalArgumentException;
void clearSlot(@NotNull DisplaySlot slot);
}

Datei anzeigen

@ -21,7 +21,7 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
String getName() throws IllegalStateException;
String getName();
/**
* Gets the name displayed to entries for this team
@ -30,17 +30,15 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
String getDisplayName() throws IllegalStateException;
String getDisplayName();
/**
* Sets the name displayed to entries for this team
*
* @param displayName New display name
* @throws IllegalArgumentException if displayName is longer than 128
* characters.
* @throws IllegalStateException if this team has been unregistered
*/
void setDisplayName(@NotNull String displayName) throws IllegalStateException, IllegalArgumentException;
void setDisplayName(@NotNull String displayName);
/**
* Gets the prefix prepended to the display of entries on this team.
@ -49,18 +47,15 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
String getPrefix() throws IllegalStateException;
String getPrefix();
/**
* Sets the prefix prepended to the display of entries on this team.
*
* @param prefix New prefix
* @throws IllegalArgumentException if prefix is null
* @throws IllegalArgumentException if prefix is longer than 64
* characters
* @throws IllegalStateException if this team has been unregistered
*/
void setPrefix(@NotNull String prefix) throws IllegalStateException, IllegalArgumentException;
void setPrefix(@NotNull String prefix);
/**
* Gets the suffix appended to the display of entries on this team.
@ -69,18 +64,15 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
String getSuffix() throws IllegalStateException;
String getSuffix();
/**
* Sets the suffix appended to the display of entries on this team.
*
* @param suffix the new suffix for this team.
* @throws IllegalArgumentException if suffix is null
* @throws IllegalArgumentException if suffix is longer than 64
* characters
* @throws IllegalStateException if this team has been unregistered
*/
void setSuffix(@NotNull String suffix) throws IllegalStateException, IllegalArgumentException;
void setSuffix(@NotNull String suffix);
/**
* Gets the color of the team.
@ -92,7 +84,7 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
ChatColor getColor() throws IllegalStateException;
ChatColor getColor();
/**
* Sets the color of the team.
@ -111,7 +103,7 @@ public interface Team {
* @return true if friendly fire is enabled
* @throws IllegalStateException if this team has been unregistered
*/
boolean allowFriendlyFire() throws IllegalStateException;
boolean allowFriendlyFire();
/**
* Sets the team friendly fire state
@ -119,7 +111,7 @@ public interface Team {
* @param enabled true if friendly fire is to be allowed
* @throws IllegalStateException if this team has been unregistered
*/
void setAllowFriendlyFire(boolean enabled) throws IllegalStateException;
void setAllowFriendlyFire(boolean enabled);
/**
* Gets the team's ability to see {@link PotionEffectType#INVISIBILITY
@ -128,7 +120,7 @@ public interface Team {
* @return true if team members can see invisible members
* @throws IllegalStateException if this team has been unregistered
*/
boolean canSeeFriendlyInvisibles() throws IllegalStateException;
boolean canSeeFriendlyInvisibles();
/**
* Sets the team's ability to see {@link PotionEffectType#INVISIBILITY
@ -137,29 +129,28 @@ public interface Team {
* @param enabled true if invisible teammates are to be visible
* @throws IllegalStateException if this team has been unregistered
*/
void setCanSeeFriendlyInvisibles(boolean enabled) throws IllegalStateException;
void setCanSeeFriendlyInvisibles(boolean enabled);
/**
* Gets the team's ability to see name tags
*
* @return the current name tag visibility for the team
* @throws IllegalArgumentException if this team has been unregistered
* @deprecated see {@link #getOption(org.bukkit.scoreboard.Team.Option)}
* @deprecated see {@link #getOption(Team.Option)}
*/
@Deprecated
@NotNull
NameTagVisibility getNameTagVisibility() throws IllegalArgumentException;
NameTagVisibility getNameTagVisibility();
/**
* Set's the team's ability to see name tags
*
* @param visibility The nameTagVisibility to set
* @throws IllegalArgumentException if this team has been unregistered
* @deprecated see
* {@link #setOption(org.bukkit.scoreboard.Team.Option, org.bukkit.scoreboard.Team.OptionStatus)}
* @deprecated see {@link #setOption(Team.Option, Team.OptionStatus)}
*/
@Deprecated
void setNameTagVisibility(@NotNull NameTagVisibility visibility) throws IllegalArgumentException;
void setNameTagVisibility(@NotNull NameTagVisibility visibility);
/**
* Gets the Set of players on the team
@ -171,16 +162,16 @@ public interface Team {
*/
@Deprecated
@NotNull
Set<OfflinePlayer> getPlayers() throws IllegalStateException;
Set<OfflinePlayer> getPlayers();
/**
* Gets the Set of entries on the team
*
* @return entries on the team
* @throws IllegalStateException if this entries has been unregistered\
* @throws IllegalStateException if this entries has been unregistered
*/
@NotNull
Set<String> getEntries() throws IllegalStateException;
Set<String> getEntries();
/**
* Gets the size of the team
@ -188,7 +179,7 @@ public interface Team {
* @return number of entries on the team
* @throws IllegalStateException if this team has been unregistered
*/
int getSize() throws IllegalStateException;
int getSize();
/**
* Gets the Scoreboard to which this team is attached
@ -205,13 +196,12 @@ public interface Team {
* This will remove the player from any other team on the scoreboard.
*
* @param player the player to add
* @throws IllegalArgumentException if player is null
* @throws IllegalStateException if this team has been unregistered
* @see #addEntry(String)
* @deprecated Teams can contain entries that aren't players
*/
@Deprecated
void addPlayer(@NotNull OfflinePlayer player) throws IllegalStateException, IllegalArgumentException;
void addPlayer(@NotNull OfflinePlayer player);
/**
* This puts the specified entry onto this team for the scoreboard.
@ -219,62 +209,57 @@ public interface Team {
* This will remove the entry from any other team on the scoreboard.
*
* @param entry the entry to add
* @throws IllegalArgumentException if entry is null
* @throws IllegalStateException if this team has been unregistered
*/
void addEntry(@NotNull String entry) throws IllegalStateException, IllegalArgumentException;
void addEntry(@NotNull String entry);
/**
* Removes the player from this team.
*
* @param player the player to remove
* @return if the player was on this team
* @throws IllegalArgumentException if player is null
* @throws IllegalStateException if this team has been unregistered
* @see #removeEntry(String)
* @deprecated Teams can contain entries that aren't players
*/
@Deprecated
boolean removePlayer(@NotNull OfflinePlayer player) throws IllegalStateException, IllegalArgumentException;
boolean removePlayer(@NotNull OfflinePlayer player);
/**
* Removes the entry from this team.
*
* @param entry the entry to remove
* @return if the entry was a part of this team
* @throws IllegalArgumentException if entry is null
* @throws IllegalStateException if this team has been unregistered
*/
boolean removeEntry(@NotNull String entry) throws IllegalStateException, IllegalArgumentException;
boolean removeEntry(@NotNull String entry);
/**
* Unregisters this team from the Scoreboard
*
* @throws IllegalStateException if this team has been unregistered
*/
void unregister() throws IllegalStateException;
void unregister();
/**
* Checks to see if the specified player is a member of this team.
*
* @param player the player to search for
* @return true if the player is a member of this team
* @throws IllegalArgumentException if player is null
* @throws IllegalStateException if this team has been unregistered
* @see #hasEntry(String)
* @deprecated Teams can contain entries that aren't players
*/
@Deprecated
boolean hasPlayer(@NotNull OfflinePlayer player) throws IllegalArgumentException, IllegalStateException;
boolean hasPlayer(@NotNull OfflinePlayer player);
/**
* Checks to see if the specified entry is a member of this team.
*
* @param entry the entry to search for
* @return true if the entry is a member of this team
* @throws IllegalArgumentException if entry is null
* @throws IllegalStateException if this team has been unregistered
*/
boolean hasEntry(@NotNull String entry) throws IllegalArgumentException, IllegalStateException;
boolean hasEntry(@NotNull String entry);
/**
* Get an option for this team
@ -284,7 +269,7 @@ public interface Team {
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
OptionStatus getOption(@NotNull Option option) throws IllegalStateException;
OptionStatus getOption(@NotNull Option option);
/**
* Set an option for this team
@ -293,7 +278,7 @@ public interface Team {
* @param status the new option status
* @throws IllegalStateException if this team has been unregistered
*/
void setOption(@NotNull Option option, @NotNull OptionStatus status) throws IllegalStateException;
void setOption(@NotNull Option option, @NotNull OptionStatus status);
/**
* Represents an option which may be applied to this team.