OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-01-08 19:34:09 +01:00
Code Issues Projects Releases Packages Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse source 
By: Edmond Poon <sagaciouszzzz@gmail.com>
This commit is contained in:
Bukkit/Spigot 2013-08-03 21:46:30 -04:00
parent b9642786eb
commit 599ec05858
80 changed files with 259 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
paper-api/src/main/java/org/bukkit/ChunkSnapshot.java
View file

@ -114,6 +114,7 @@ public interface ChunkSnapshot {
/**
* Test if section is empty
*
* @param sy - section Y coordinate (block Y / 16)
* @return true if empty, false if not
*/

1
paper-api/src/main/java/org/bukkit/FireworkEffect.java
View file

@ -54,6 +54,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
/**
* This is a builder for FireworkEffects.
*
* @see FireworkEffect#builder()
*/
public static final class Builder {

1
paper-api/src/main/java/org/bukkit/Instrument.java
View file

@ -43,6 +43,7 @@ public enum Instrument {
/**
* Get an instrument by its type ID.
*
* @param type The type ID
* @return The instrument
*/

7
paper-api/src/main/java/org/bukkit/Server.java
View file

@ -608,6 +608,7 @@ public interface Server extends PluginMessageRecipient {
* Creates an empty inventory of the specified type. If the type is {@link InventoryType#CHEST},
* the new inventory has a size of 27; otherwise the new inventory has the normal size for
* its type.
*
* @param owner The holder of the inventory; can be null if there's no holder.
* @param type The type of inventory to create.
* @return The new inventory.
@ -616,6 +617,7 @@ public interface Server extends PluginMessageRecipient {
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size.
*
* @param owner The holder of the inventory; can be null if there's no holder.
* @param size The size of inventory to create; must be a multiple of 9.
* @return The new inventory.
@ -625,6 +627,7 @@ public interface Server extends PluginMessageRecipient {
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size and title.
*
* @param owner The holder of the inventory; can be null if there's no holder.
* @param size The size of inventory to create; must be a multiple of 9.
* @param title The title of the inventory, to be displayed when it is viewed.
@ -635,24 +638,28 @@ public interface Server extends PluginMessageRecipient {
/**
* Gets user-specified limit for number of monsters that can spawn in a chunk
*
* @return The monster spawn limit
*/
int getMonsterSpawnLimit();
/**
* Gets user-specified limit for number of animals that can spawn in a chunk
*
* @return The animal spawn limit
*/
int getAnimalSpawnLimit();
/**
* Gets user-specified limit for number of water animals that can spawn in a chunk
*
* @return The water animal spawn limit
*/
int getWaterAnimalSpawnLimit();
/**
* Gets user-specified limit for number of ambient mobs that can spawn in a chunk
*
* @return The ambient spawn limit
*/
int getAmbientSpawnLimit();

4
paper-api/src/main/java/org/bukkit/Warning.java
View file

@ -50,6 +50,7 @@ public @interface Warning {
/**
* This method checks the provided warning should be printed for this state
*
* @param warning The warning annotation added to a deprecated item
* @return ON is always True<br>
* OFF is always false<br>
@ -64,6 +65,7 @@ public @interface Warning {
/**
* This method returns the corresponding warning state for the given string value.
*
* @param value The string value to check
* @return {@link #DEFAULT} if not found, or the respective WarningState
*/
@ -81,12 +83,14 @@ public @interface Warning {
/**
* This sets if the deprecation warnings when registering events gets printed when the setting is in the default state.
*
* @return false normally, or true to encourage warning printout
*/
boolean value() default false;
/**
* This can provide detailed information on why the event is deprecated.
*
* @return The reason an event is deprecated
*/
String reason() default "";

4
paper-api/src/main/java/org/bukkit/World.java
View file

@ -972,6 +972,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
/**
* Gets the limit for number of animals that can spawn in a chunk in this world
*
* @return The animal spawn limit
*/
int getAnimalSpawnLimit();
@ -986,6 +987,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
/**
* Gets the limit for number of water animals that can spawn in a chunk in this world
*
* @return The water animal spawn limit
*/
int getWaterAnimalSpawnLimit();
@ -1000,6 +1002,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
/**
* Gets the limit for number of ambient mobs that can spawn in a chunk in this world
*
* @return The ambient spawn limit
*/
int getAmbientSpawnLimit();
@ -1098,6 +1101,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
/**
* Get an environment by ID
*
* @param id The ID of the environment
* @return The environment
*/

1
paper-api/src/main/java/org/bukkit/conversations/BooleanPrompt.java
View file

@ -25,6 +25,7 @@ public abstract class BooleanPrompt extends ValidatingPrompt{
/**
* Override this method to perform some action with the user's boolean response.
*
* @param context Context information about the conversation.
* @param input The user's boolean response.
* @return The next {@link Prompt} in the prompt graph.

5
paper-api/src/main/java/org/bukkit/conversations/Conversable.java
View file

@ -9,6 +9,7 @@ public interface Conversable {
/**
* Tests to see of a Conversable object is actively engaged in a conversation.
*
* @return True if a conversation is in progress
*/
public boolean isConversing();
@ -16,12 +17,14 @@ public interface Conversable {
/**
* Accepts input into the active conversation. If no conversation is in progress,
* this method does nothing.
*
* @param input The input message into the conversation
*/
public void acceptConversationInput(String input);
/**
* Enters into a dialog with a Conversation object.
*
* @param conversation The conversation to begin
* @return True if the conversation should proceed, false if it has been enqueued
*/
@ -29,12 +32,14 @@ public interface Conversable {
/**
* Abandons an active conversation.
*
* @param conversation The conversation to abandon
*/
public void abandonConversation(Conversation conversation);
/**
* Abandons an active conversation.
*
* @param conversation The conversation to abandon
* @param details Details about why the conversation was abandoned
*/

20
paper-api/src/main/java/org/bukkit/conversations/Conversation.java
View file

@ -11,18 +11,18 @@ import java.util.Map;
* The Conversation class is responsible for tracking the current state of a conversation, displaying prompts to
* the user, and dispatching the user's response to the appropriate place. Conversation objects are not typically
* instantiated directly. Instead a {@link ConversationFactory} is used to construct identical conversations on demand.
*
* <p>
* Conversation flow consists of a directed graph of {@link Prompt} objects. Each time a prompt gets input from the
* user, it must return the next prompt in the graph. Since each Prompt chooses the next Prompt, complex conversation
* trees can be implemented where the nature of the player's response directs the flow of the conversation.
*
* <p>
* Each conversation has a {@link ConversationPrefix} that prepends all output from the conversation to the player.
* The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves.
*
* <p>
* Each conversation has a timeout measured in the number of inactive seconds to wait before abandoning the conversation.
* If the inactivity timeout is reached, the conversation is abandoned and the user's incoming and outgoing chat is
* returned to normal.
*
* <p>
* You should not construct a conversation manually. Instead, use the {@link ConversationFactory} for access to all
* available options.
*/
@ -40,6 +40,7 @@ public class Conversation {
/**
* Initializes a new Conversation.
*
* @param plugin The plugin that owns this conversation.
* @param forWhom The entity for whom this conversation is mediating.
* @param firstPrompt The first prompt in the conversation graph.
@ -50,6 +51,7 @@ public class Conversation {
/**
* Initializes a new Conversation.
*
* @param plugin The plugin that owns this conversation.
* @param forWhom The entity for whom this conversation is mediating.
* @param firstPrompt The first prompt in the conversation graph.
@ -67,6 +69,7 @@ public class Conversation {
/**
* Gets the entity for whom this conversation is mediating.
*
* @return The entity.
*/
public Conversable getForWhom() {
@ -76,6 +79,7 @@ public class Conversation {
/**
* Gets the modality of this conversation. If a conversation is modal, all messages directed to the player
* are suppressed for the duration of the conversation.
*
* @return The conversation modality.
*/
public boolean isModal() {
@ -85,6 +89,7 @@ public class Conversation {
/**
* Sets the modality of this conversation. If a conversation is modal, all messages directed to the player
* are suppressed for the duration of the conversation.
*
* @param modal The new conversation modality.
*/
void setModal(boolean modal) {
@ -94,6 +99,7 @@ public class Conversation {
/**
* Gets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
* gets echoed back into the submitter's chat window.
*
* @return The status of local echo.
*/
public boolean isLocalEchoEnabled() {
@ -103,6 +109,7 @@ public class Conversation {
/**
* Sets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
* gets echoed back into the submitter's chat window.
*
* @param localEchoEnabled The status of local echo.
*/
public void setLocalEchoEnabled(boolean localEchoEnabled) {
@ -111,6 +118,7 @@ public class Conversation {
/**
* Gets the {@link ConversationPrefix} that prepends all output from this conversation.
*
* @return The ConversationPrefix in use.
*/
public ConversationPrefix getPrefix() {
@ -119,6 +127,7 @@ public class Conversation {
/**
* Sets the {@link ConversationPrefix} that prepends all output from this conversation.
*
* @param prefix The ConversationPrefix to use.
*/
void setPrefix(ConversationPrefix prefix) {
@ -127,6 +136,7 @@ public class Conversation {
/**
* Adds a {@link ConversationCanceller} to the cancellers collection.
*
* @param canceller The {@link ConversationCanceller} to add.
*/
void addConversationCanceller(ConversationCanceller canceller) {
@ -136,6 +146,7 @@ public class Conversation {
/**
* Gets the list of {@link ConversationCanceller}s
*
* @return The list.
*/
public List<ConversationCanceller> getCancellers() {
@ -144,6 +155,7 @@ public class Conversation {
/**
* Returns the Conversation's {@link ConversationContext}.
*
* @return The ConversationContext.
*/
public ConversationContext getContext() {

3
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java
View file

@ -22,6 +22,7 @@ public class ConversationAbandonedEvent extends EventObject {
/**
* Gets the object that caused the conversation to be abandoned.
*
* @return The object that abandoned the conversation.
*/
public ConversationCanceller getCanceller() {
@ -30,6 +31,7 @@ public class ConversationAbandonedEvent extends EventObject {
/**
* Gets the abandoned conversation's conversation context.
*
* @return The abandoned conversation's conversation context.
*/
public ConversationContext getContext() {
@ -39,6 +41,7 @@ public class ConversationAbandonedEvent extends EventObject {
/**
* Indicates how the conversation was abandoned - naturally as part of the prompt chain or prematurely via a
* {@link ConversationCanceller}.
*
* @return True if the conversation is abandoned gracefully by a {@link Prompt} returning null
* or the next prompt. False of the conversations is abandoned prematurely by a ConversationCanceller.
*/

1
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java
View file

@ -7,6 +7,7 @@ import java.util.EventListener;
public interface ConversationAbandonedListener extends EventListener {
/**
* Called whenever a {@link Conversation} is abandoned.
*
* @param abandonedEvent Contains details about the abandoned conversation.
*/
public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent);

6
paper-api/src/main/java/org/bukkit/conversations/ConversationCanceller.java
View file

@ -8,12 +8,14 @@ public interface ConversationCanceller extends Cloneable {
/**
* Sets the conversation this ConversationCanceller can optionally cancel.
*
* @param conversation A conversation.
*/
public void setConversation(Conversation conversation);
/**
* Cancels a conversation based on user input/
* Cancels a conversation based on user input.
*
* @param context Context information about the conversation.
* @param input The input text from the user.
* @return True to cancel the conversation, False otherwise.
@ -22,7 +24,9 @@ public interface ConversationCanceller extends Cloneable {
/**
* Allows the {@link ConversationFactory} to duplicate this ConversationCanceller when creating a new {@link Conversation}.
* <p>
* Implementing this method should reset any internal object state.
*
* @return A clone.
*/
public ConversationCanceller clone();

4
paper-api/src/main/java/org/bukkit/conversations/ConversationContext.java
View file

@ -27,6 +27,7 @@ public class ConversationContext {
/**
* Gets the plugin that owns this conversation.
*
* @return The owning plugin.
*/
public Plugin getPlugin() {
@ -35,6 +36,7 @@ public class ConversationContext {
/**
* Gets the subject of the conversation.
*
* @return The subject of the conversation.
*/
public Conversable getForWhom() {
@ -44,6 +46,7 @@ public class ConversationContext {
/**
* Gets session data shared between all {@link Prompt} invocations. Use this as a way
* to pass data through each Prompt as the conversation develops.
*
* @param key The session data key.
* @return The requested session data.
*/
@ -54,6 +57,7 @@ public class ConversationContext {
/**
* Sets session data shared between all {@link Prompt} invocations. Use this as a way to pass
* data through each prompt as the conversation develops.
*
* @param key The session data key.
* @param value The session data value.
*/

22
paper-api/src/main/java/org/bukkit/conversations/ConversationFactory.java
View file

@ -12,7 +12,7 @@ import java.util.Map;
* A ConversationFactory is responsible for creating a {@link Conversation} from a predefined template. A ConversationFactory
* is typically created when a plugin is instantiated and builds a Conversation each time a user initiates a conversation
* with the plugin. Each Conversation maintains its own state and calls back as needed into the plugin.
*
* <p>
* The ConversationFactory implements a fluid API, allowing parameters to be set as an extension to the constructor.
*/
public class ConversationFactory {
@ -29,6 +29,7 @@ public class ConversationFactory {
/**
* Constructs a ConversationFactory.
*
* @param plugin The plugin that owns the factory.
*/
public ConversationFactory(Plugin plugin)
@ -47,8 +48,9 @@ public class ConversationFactory {
/**
* Sets the modality of all {@link Conversation}s created by this factory. If a conversation is modal, all messages
* directed to the player are suppressed for the duration of the conversation.
*
* <p>
* The default is True.
*
* @param modal The modality of all conversations to be created.
* @return This object.
*/
@ -61,6 +63,7 @@ public class ConversationFactory {
/**
* Sets the local echo status for all {@link Conversation}s created by this factory. If local echo is enabled,
* any text submitted to a conversation gets echoed back into the submitter's chat window.
*
* @param localEchoEnabled The status of local echo.
* @return This object.
*/
@ -71,8 +74,9 @@ public class ConversationFactory {
/**
* Sets the {@link ConversationPrefix} that prepends all output from all generated conversations.
*
* <p>
* The default is a {@link NullConversationPrefix};
*
* @param prefix The ConversationPrefix to use.
* @return This object.
*/
@ -83,8 +87,9 @@ public class ConversationFactory {
/**
* Sets the number of inactive seconds to wait before automatically abandoning all generated conversations.
*
* <p>
* The default is 600 seconds (5 minutes).
*
* @param timeoutSeconds The number of seconds to wait.
* @return This object.
*/
@ -94,8 +99,9 @@ public class ConversationFactory {
/**
* Sets the first prompt to use in all generated conversations.
*
* <p>
* The default is Prompt.END_OF_CONVERSATION.
*
* @param firstPrompt The first prompt.
* @return This object.
*/
@ -106,6 +112,7 @@ public class ConversationFactory {
/**
* Sets any initial data with which to populate the conversation context sessionData map.
*
* @param initialSessionData The conversation context's initial sessionData.
* @return This object.
*/
@ -116,6 +123,7 @@ public class ConversationFactory {
/**
* Sets the player input that, when received, will immediately terminate the conversation.
*
* @param escapeSequence Input to terminate the conversation.
* @return This object.
*/
@ -126,6 +134,7 @@ public class ConversationFactory {
/**
* Adds a {@link ConversationCanceller to constructed conversations.}
*
* @param canceller The {@link ConversationCanceller to add.}
* @return This object.
*/
@ -136,6 +145,7 @@ public class ConversationFactory {
/**
* Prevents this factory from creating a conversation for non-player {@link Conversable} objects.
*
* @param playerOnlyMessage The message to return to a non-play in lieu of starting a conversation.
* @return This object.
*/
@ -146,6 +156,7 @@ public class ConversationFactory {
/**
* Adds a {@link ConversationAbandonedListener} to all conversations constructed by this factory.
*
* @param listener The listener to add.
* @return This object.
*/
@ -156,6 +167,7 @@ public class ConversationFactory {
/**
* Constructs a {@link Conversation} in accordance with the defaults set for this factory.
*
* @param forWhom The entity for whom the new conversation is mediating.
* @return A new conversation.
*/

1
paper-api/src/main/java/org/bukkit/conversations/ConversationPrefix.java
View file

@ -10,6 +10,7 @@ public interface ConversationPrefix {
/**
* Gets the prefix to use before each message to the player.
*
* @param context Context information about the conversation.
* @return The prefix text.
*/

1
paper-api/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java
View file

@ -8,6 +8,7 @@ public class ExactMatchConversationCanceller implements ConversationCanceller {
/**
* Builds an ExactMatchConversationCanceller.
*
* @param escapeSequence The string that, if entered by the user, will cancel the conversation.
*/
public ExactMatchConversationCanceller(String escapeSequence) {

3
paper-api/src/main/java/org/bukkit/conversations/FixedSetPrompt.java
View file

@ -15,6 +15,7 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
/**
* Creates a FixedSetPrompt from a set of strings.
* foo = new FixedSetPrompt("bar", "cheese", "panda");
*
* @param fixedSet A fixed set of strings, one of which the user must type.
*/
public FixedSetPrompt(String... fixedSet) {
@ -31,7 +32,7 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
/**
* Utility function to create a formatted string containing all the options declared in the constructor.
*
*
* @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used
*/
protected String formatFixedSet() {

2
paper-api/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java
View file

@ -14,6 +14,7 @@ public class InactivityConversationCanceller implements ConversationCanceller {
/**
* Creates an InactivityConversationCanceller.
*
* @param plugin The owning plugin.
* @param timeoutSeconds The number of seconds of inactivity to wait.
*/
@ -67,6 +68,7 @@ public class InactivityConversationCanceller implements ConversationCanceller {
/**
* Subclasses of InactivityConversationCanceller can override this method to take additional actions when the
* inactivity timer abandons the conversation.
*
* @param conversation The conversation being abandoned.
*/
protected void cancelling(Conversation conversation) {

3
paper-api/src/main/java/org/bukkit/conversations/MessagePrompt.java
View file

@ -11,6 +11,7 @@ public abstract class MessagePrompt implements Prompt{
/**
* Message prompts never wait for user input before continuing.
*
* @param context Context information about the conversation.
* @return Always false.
*/
@ -20,6 +21,7 @@ public abstract class MessagePrompt implements Prompt{
/**
* Accepts and ignores any user input, returning the next prompt in the prompt graph instead.
*
* @param context Context information about the conversation.
* @param input Ignored.
* @return The next prompt in the prompt graph.
@ -30,6 +32,7 @@ public abstract class MessagePrompt implements Prompt{
/**
* Override this method to return the next prompt in the prompt graph.
*
* @param context Context information about the conversation.
* @return The next prompt in the prompt graph.
*/

1
paper-api/src/main/java/org/bukkit/conversations/NullConversationPrefix.java
View file

@ -10,6 +10,7 @@ public class NullConversationPrefix implements ConversationPrefix{
/**
* Prepends each conversation message with an empty string.
*
* @param context Context information about the conversation.
* @return An empty string.
*/

4
paper-api/src/main/java/org/bukkit/conversations/NumericPrompt.java
View file

@ -18,6 +18,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
/**
* Override this method to do further validation on the numeric player input after the input has been determined
* to actually be a number.
*
* @param context Context information about the conversation.
* @param input The number the player provided.
* @return The validity of the player's input.
@ -38,6 +39,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
/**
* Override this method to perform some action with the user's integer response.
*
* @param context Context information about the conversation.
* @param input The user's response as a {@link Number}.
* @return The next {@link Prompt} in the prompt graph.
@ -55,6 +57,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
/**
* Optionally override this method to display an additional message if the user enters an invalid number.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.
* @return A message explaining how to correct the input.
@ -65,6 +68,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
/**
* Optionally override this method to display an additional message if the user enters an invalid numeric input.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.
* @return A message explaining how to correct the input.

1
paper-api/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java
View file

@ -27,6 +27,7 @@ public abstract class PlayerNamePrompt extends ValidatingPrompt{
/**
* Override this method to perform some action with the user's player name response.
*
* @param context Context information about the conversation.
* @param input The user's player name response.
* @return The next {@link Prompt} in the prompt graph.

1
paper-api/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java
View file

@ -30,6 +30,7 @@ public class PluginNameConversationPrefix implements ConversationPrefix {
/**
* Prepends each conversation message with the plugin name.
*
* @param context Context information about the conversation.
* @return An empty string.
*/

3
paper-api/src/main/java/org/bukkit/conversations/Prompt.java
View file

@ -14,6 +14,7 @@ public interface Prompt extends Cloneable {
/**
* Gets the text to display to the user when this prompt is first presented.
*
* @param context Context information about the conversation.
* @return The text to display.
*/
@ -21,6 +22,7 @@ public interface Prompt extends Cloneable {
/**
* Checks to see if this prompt implementation should wait for user input or immediately display the next prompt.
*
* @param context Context information about the conversation.
* @return If true, the {@link Conversation} will wait for input before continuing.
*/
@ -28,6 +30,7 @@ public interface Prompt extends Cloneable {
/**
* Accepts and processes input from the user. Using the input, the next Prompt in the prompt graph is returned.
*
* @param context Context information about the conversation.
* @param input The input text from the user.
* @return The next Prompt in the prompt graph.

1
paper-api/src/main/java/org/bukkit/conversations/StringPrompt.java
View file

@ -7,6 +7,7 @@ public abstract class StringPrompt implements Prompt{
/**
* Ensures that the prompt waits for the user to provide input.
*
* @param context Context information about the conversation.
* @return True.
*/

5
paper-api/src/main/java/org/bukkit/conversations/ValidatingPrompt.java
View file

@ -14,6 +14,7 @@ public abstract class ValidatingPrompt implements Prompt {
/**
* Accepts and processes input from the user and validates it. If validation fails, this prompt is returned for
* re-execution, otherwise the next Prompt in the prompt graph is returned.
*
* @param context Context information about the conversation.
* @param input The input text from the user.
* @return This prompt or the next Prompt in the prompt graph.
@ -33,6 +34,7 @@ public abstract class ValidatingPrompt implements Prompt {
/**
* Ensures that the prompt waits for the user to provide input.
*
* @param context Context information about the conversation.
* @return True.
*/
@ -42,6 +44,7 @@ public abstract class ValidatingPrompt implements Prompt {
/**
* Override this method to check the validity of the player's input.
*
* @param context Context information about the conversation.
* @param input The player's raw console input.
* @return True or false depending on the validity of the input.
@ -51,6 +54,7 @@ public abstract class ValidatingPrompt implements Prompt {
/**
* Override this method to accept and processes the validated input from the user. Using the input, the next Prompt
* in the prompt graph should be returned.
*
* @param context Context information about the conversation.
* @param input The validated input text from the user.
* @return The next Prompt in the prompt graph.
@ -59,6 +63,7 @@ public abstract class ValidatingPrompt implements Prompt {
/**
* Optionally override this method to display an additional message if the user enters an invalid input.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.
* @return A message explaining how to correct the input.

1
paper-api/src/main/java/org/bukkit/entity/AnimalTamer.java
View file

@ -3,6 +3,7 @@ package org.bukkit.entity;
public interface AnimalTamer {
/**
* This is the name of the specified AnimalTamer.
*
* @return The name to reference on tamed animals
*/
public String getName();

1
paper-api/src/main/java/org/bukkit/entity/CreatureType.java
View file

@ -6,6 +6,7 @@ import java.util.Map;
/**
* Represents a type of creature.
*
* @deprecated Use EntityType instead.
*/
@Deprecated

3
paper-api/src/main/java/org/bukkit/entity/EntityType.java
View file

@ -39,7 +39,7 @@ public enum EntityType {
*/
ARROW("Arrow", Arrow.class, 10),
/**
* A flyinf snowball.
* A flying snowball.
*/
SNOWBALL("Snowball", Snowball.class, 11),
/**
@ -227,6 +227,7 @@ public enum EntityType {
* Some entities cannot be spawned using {@link World#spawnEntity(Location, EntityType)}
* or {@link World#spawn(Location, Class)}, usually
* because they require additional information in order to spawn.
*
* @return False if the entity type cannot be spawned
*/
public boolean isSpawnable() {

8
paper-api/src/main/java/org/bukkit/entity/HumanEntity.java
View file

@ -38,6 +38,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/**
* If the player currently has an inventory window open, this method will set a
* property of that window, such as the state of a progress bar.
*
* @param prop The property.
* @param value The value to set the property to.
* @return True if the property was successfully set.
@ -47,6 +48,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/**
* Gets the inventory view the player is currently viewing. If they do not have
* an inventory window open, it returns their internal crafting view.
*
* @return The inventory view.
*/
public InventoryView getOpenInventory();
@ -54,6 +56,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/**
* Opens an inventory window with the specified inventory on the top and the player's inventory
* on the bottom.
*
* @param inventory The inventory to open
* @return The newly opened inventory view
*/
@ -61,6 +64,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/**
* Opens an empty workbench inventory window with the player's inventory on the bottom.
*
* @param location The location to attach it to. If null, the player's location is used.
* @param force If false, and there is no workbench block at the location, no inventory will be
* opened and null will be returned.
@ -70,6 +74,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/**
* Opens an empty enchanting inventory window with the player's inventory on the bottom.
*
* @param location The location to attach it to. If null, the player's location is used.
* @param force If false, and there is no enchanting table at the location, no inventory will be
* opened and null will be returned.
@ -78,7 +83,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
public InventoryView openEnchanting(Location location, boolean force);
/**
* Opens an inventory window to the specified inventory view
* Opens an inventory window to the specified inventory view.
*
* @param inventory The view to open
*/
public void openInventory(InventoryView inventory);

2
paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
View file

@ -305,7 +305,7 @@ public interface LivingEntity extends Entity, Damageable {
public void setRemoveWhenFarAway(boolean remove);
/**
* Gets the inventory with the equipment worn by the living entity.
* Gets the inventory with the equipment worn by the living entity.
*
* @return the living entity's inventory
*/

4
paper-api/src/main/java/org/bukkit/entity/Player.java
View file

@ -596,6 +596,7 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
/**
* Sets the speed at which a client will fly. Negative values indicate reverse directions.
*
* @param value The new speed, from -1 to 1.
* @throws IllegalArgumentException If new speed is less than -1 or greater than 1
*/
@ -603,6 +604,7 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
/**
* Sets the speed at which a client will walk. Negative values indicate reverse directions.
*
* @param value The new speed, from -1 to 1.
* @throws IllegalArgumentException If new speed is less than -1 or greater than 1
*/
@ -610,12 +612,14 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
/**
* Gets the current allowed speed that a client can fly.
*
* @return The current allowed speed, from -1 to 1
*/
public float getFlySpeed();
/**
* Gets the current allowed speed that a client can walk.
*
* @return The current allowed speed, from -1 to 1
*/
public float getWalkSpeed();

2
paper-api/src/main/java/org/bukkit/entity/TNTPrimed.java
View file

@ -26,7 +26,7 @@ public interface TNTPrimed extends Explosive {
* that this can be null if there is no suitable source.
* (created by the {@link org.bukkit.World#spawn(Location, Class)}
* method, for example.)
*
* <p>
* The source will become null if the chunk this primed TNT is in
* is unloaded then reloaded. If the source Entity becomes invalidated
* for any reason, such being removed from the world, the returned value

1
paper-api/src/main/java/org/bukkit/event/HandlerList.java
View file

@ -193,7 +193,6 @@ public class HandlerList {
* Get a specific plugin's registered listeners associated with this handler list
*
* @param plugin the plugin to get the listeners of
*
* @return the list of registered listeners
*/
public static ArrayList<RegisteredListener> getRegisteredListeners(Plugin plugin) {

4
paper-api/src/main/java/org/bukkit/event/entity/ExpBottleEvent.java
View file

@ -23,6 +23,7 @@ public class ExpBottleEvent extends ProjectileHitEvent {
/**
* This method indicates if the particle effect should be shown.
*
* @return true if the effect will be shown, false otherwise
*/
public boolean getShowEffect() {
@ -32,6 +33,7 @@ public class ExpBottleEvent extends ProjectileHitEvent {
/**
* This method sets if the particle effect will be shown.
* This does not change the experience created.
*
* @param showEffect
* true indicates the effect will be shown,
* false indicates no effect will be shown
@ -43,6 +45,7 @@ public class ExpBottleEvent extends ProjectileHitEvent {
/**
* This method retrieves the amount of experience to be created.
* The number indicates a total amount to be divided into orbs.
*
* @return the total amount of experience to be created
*/
public int getExperience() {
@ -52,6 +55,7 @@ public class ExpBottleEvent extends ProjectileHitEvent {
/**
* This method sets the amount of experience to be created.
* The number indicates a total amount to be divided into orbs.
*
* @param exp the total amount of experience to be created
*/
public void setExperience(final int exp) {

8
paper-api/src/main/java/org/bukkit/event/inventory/BrewEvent.java
View file

@ -6,6 +6,9 @@ import org.bukkit.event.HandlerList;
import org.bukkit.event.block.BlockEvent;
import org.bukkit.inventory.BrewerInventory;
/**
* Called when the brewing of the contents inside the Brewing Stand is complete.
*/
public class BrewEvent extends BlockEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private BrewerInventory contents;
@ -16,6 +19,11 @@ public class BrewEvent extends BlockEvent implements Cancellable {
this.contents = contents;
}
/**
* Gets the contents of the Brewing Stand.
*
* @return the contents
*/
public BrewerInventory getContents() {
return contents;
}

1
paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
View file

@ -17,6 +17,7 @@ public class InventoryCloseEvent extends InventoryEvent {
/**
* Returns the player involved in this event
*
* @return Player who is involved in this event
*/
public final HumanEntity getPlayer() {

6
paper-api/src/main/java/org/bukkit/event/inventory/InventoryMoveItemEvent.java
View file

@ -10,14 +10,14 @@ import org.bukkit.inventory.ItemStack;
/**
* Called when some entity or block (e.g. hopper) tries to move items
* directly from one inventory to another.
*
* <p>
* When this event is called, the initiator may already have removed the item
* from the source inventory and is ready to move it into the destination
* inventory.
*
* <p>
* If this event is cancelled, the items will be returned to the source
* inventory, if needed.
*
* <p>
* If this event is not cancelled, the initiator will try to put the
* ItemStack into the destination inventory. If this is not possible and the
* ItemStack has not been modified, the source inventory slot will be

10
paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
View file

@ -1,4 +1,3 @@
package org.bukkit.event.inventory;
import org.bukkit.inventory.InventoryView;
@ -20,6 +19,7 @@ public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
/**
* Returns the player involved in this event
*
* @return Player who is involved in this event
*/
public final HumanEntity getPlayer() {
@ -28,8 +28,8 @@ public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
/**
* Gets the cancellation state of this event. A cancelled event will not
* be executed in the server, but will still pass to other plugins
*
* be executed in the server, but will still pass to other plugins.
* <p>
* If an inventory open event is cancelled, the inventory screen will not show.
*
* @return true if this event is cancelled
@ -40,8 +40,8 @@ public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
/**
* Sets the cancellation state of this event. A cancelled event will not
* be executed in the server, but will still pass to other plugins
*
* be executed in the server, but will still pass to other plugins.
* <p>
* If an inventory open event is cancelled, the inventory screen will not show.
*
* @param cancel true if you wish to cancel this event

2
paper-api/src/main/java/org/bukkit/event/inventory/PrepareItemCraftEvent.java
View file

@ -19,6 +19,7 @@ public class PrepareItemCraftEvent extends InventoryEvent {
/**
* Get the recipe that has been formed. If this event was triggered by a tool repair, this
* will be a temporary shapeless recipe representing the repair.
*
* @return The recipe being crafted.
*/
public Recipe getRecipe() {
@ -35,6 +36,7 @@ public class PrepareItemCraftEvent extends InventoryEvent {
/**
* Check if this event was triggered by a tool repair operation rather than a crafting recipe.
*
* @return True if this is a repair.
*/
public boolean isRepair() {

8
paper-api/src/main/java/org/bukkit/event/player/PlayerChangedWorldEvent.java
View file

@ -4,6 +4,9 @@ import org.bukkit.World;
import org.bukkit.entity.Player;
import org.bukkit.event.HandlerList;
/**
* Called when a player switches to another world.
*/
public class PlayerChangedWorldEvent extends PlayerEvent {
private static final HandlerList handlers = new HandlerList();
private final World from;
@ -13,6 +16,11 @@ public class PlayerChangedWorldEvent extends PlayerEvent {
this.from = from;
}
/**
* Gets the world the player is switching from.
*
* @return player's previous world
*/
public World getFrom() {
return from;
}

1
paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
View file

@ -109,6 +109,7 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
* The set returned is not guaranteed to be mutable and may auto-populate on access.
* Any listener accessing the returned set should be aware that it may reduce performance for a lazy set implementation.
* Listeners should be aware that modifying the list may throw {@link UnsupportedOperationException} if the event caller provides an unmodifiable set.
*
* @deprecated This method is provided for backward compatibility with no guarantee to the effect of viewing or modifying the set.
* @return All Players who will see this chat message
*/

1
paper-api/src/main/java/org/bukkit/event/player/PlayerFishEvent.java
View file

@ -47,6 +47,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
/**
* Gets the fishing hook.
*
* @return Fish the entity representing the fishing hook/bobber.
*/
public Fish getHook() {

8
paper-api/src/main/java/org/bukkit/event/player/PlayerGameModeChangeEvent.java
View file

@ -5,6 +5,9 @@ import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Called when the GameMode of the player is changed.
*/
public class PlayerGameModeChangeEvent extends PlayerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private boolean cancelled;
@ -23,6 +26,11 @@ public class PlayerGameModeChangeEvent extends PlayerEvent implements Cancellabl
this.cancelled = cancel;
}
/**
* Gets the GameMode the player is switched to.
*
* @return player's new GameMode
*/
public GameMode getNewGameMode() {
return newGameMode;
}

1
paper-api/src/main/java/org/bukkit/event/player/PlayerItemConsumeEvent.java
View file

@ -22,7 +22,6 @@ public class PlayerItemConsumeEvent extends PlayerEvent implements Cancellable {
private ItemStack item;
/**
*
* @param player the player consuming
* @param item the ItemStack being consumed
*/

3
paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java
View file

@ -16,12 +16,13 @@ import org.bukkit.block.Block;
public abstract class ChunkGenerator {
/**
* Interface to biome data for chunk to be generated: initialized with default values for world type and seed.
*
* <p>
* Custom generator is free to access and tailor values during generateBlockSections() or generateExtBlockSections().
*/
public interface BiomeGrid {
/**
* Get biome at x, z within chunk being generated
*
* @param x - 0-15
* @param z - 0-15
* @return Biome value

8
paper-api/src/main/java/org/bukkit/help/HelpTopic.java
View file

@ -5,11 +5,11 @@ import org.bukkit.entity.Player;
/**
* HelpTopic implementations are displayed to the user when the user uses the /help command.
*
* <p>
* Custom implementations of this class can work at two levels. A simple implementation only
* needs to set the value of {@code name}, {@code shortText}, and {@code fullText} int the
* constructor. This base class will take care of the rest.
*
* <p>
* Complex implementations can be created by overriding the behavior of all the methods in
* this class.
*/
@ -32,6 +32,7 @@ public abstract class HelpTopic {
* Allows the server administrator to override the permission required to see a help topic. HelpTopic
* implementations should take this into account when determining topic visibility on the
* {@link HelpTopic#canSee(org.bukkit.command.CommandSender)} function.
*
* @param amendedPermission The permission node the server administrator wishes to apply to this topic.
*/
public void amendCanSee(String amendedPermission) {
@ -40,6 +41,7 @@ public abstract class HelpTopic {
/**
* Returns the name of this help topic.
*
* @return The topic name.
*/
public String getName() {
@ -48,6 +50,7 @@ public abstract class HelpTopic {
/**
* Returns a brief description that will be displayed in the topic index.
*
* @return A brief topic description.
*/
public String getShortText() {
@ -88,7 +91,6 @@ public abstract class HelpTopic {
*
* @param baseText The existing text of the help topic.
* @param amendment The amending text from the amendTopic() method.
*
* @return The application of the amending text to the existing text, according to the expected rules of
* amendTopic().
*/

4
paper-api/src/main/java/org/bukkit/help/HelpTopicFactory.java
View file

@ -7,13 +7,13 @@ import org.bukkit.command.Command;
* common base class or have executors that inherit from a common base class. You can use a custom HelpTopic to change
* the way all the commands in your plugin display in the help. If your plugin implements a complex permissions system,
* a custom help topic may also be appropriate.
*
* <p>
* To automatically bind your plugin's commands to your custom HelpTopic implementation, first make sure all your
* commands or executors derive from a custom base class (it doesn't have to do anything). Next implement a custom
* HelpTopicFactory that accepts your custom command base class and instantiates an instance of your custom HelpTopic
* from it. Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)}
* method.
*
* <p>
* As the help system iterates over all registered commands to make help topics, it first checks to see if there is a
* HelpTopicFactory registered for the command's base class. If so, the factory is used to make a help topic rather
* than a generic help topic. If no factory is found for the command's base class and the command derives from

2
paper-api/src/main/java/org/bukkit/inventory/BeaconInventory.java
View file

@ -3,11 +3,13 @@ package org.bukkit.inventory;
public interface BeaconInventory extends Inventory {
/**
* Set the item powering the beacon.
*
* @param item The new item
*/
void setItem(ItemStack item);
/**
* Get the item powering the beacon.
*
* @return The current item.
*/
ItemStack getItem();

2
paper-api/src/main/java/org/bukkit/inventory/BrewerInventory.java
View file

@ -5,11 +5,13 @@ import org.bukkit.block.BrewingStand;
public interface BrewerInventory extends Inventory {
/**
* Get the current ingredient for brewing.
*
* @return The ingredient.
*/
ItemStack getIngredient();
/**
* Set the current ingredient for brewing.
*
* @param ingredient The ingredient
*/
void setIngredient(ItemStack ingredient);

5
paper-api/src/main/java/org/bukkit/inventory/CraftingInventory.java
View file

@ -6,27 +6,32 @@ package org.bukkit.inventory;
public interface CraftingInventory extends Inventory {
/**
* Check what item is in the result slot of this crafting inventory.
*
* @return The result item.
*/
ItemStack getResult();
/**
* Get the contents of the crafting matrix.
*
* @return The contents.
*/
ItemStack[] getMatrix();
/**
* Set the item in the result slot of the crafting inventory.
*
* @param newResult The new result item.
*/
void setResult(ItemStack newResult);
/**
* Replace the contents of the crafting matrix
*
* @param contents The new contents.
* @throws IllegalArgumentException if the length of contents is greater than the size of the crafting matrix.
*/
void setMatrix(ItemStack[] contents);
/**
* Get the current recipe formed on the crafting inventory, if any.
*
* @return The recipe, or null if the current contents don't match any recipe.
*/
Recipe getRecipe();

2
paper-api/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
View file

@ -5,12 +5,14 @@ import org.bukkit.block.DoubleChest;
public interface DoubleChestInventory extends Inventory {
/**
* Get the left half of this double chest.
*
* @return The left side inventory
*/
Inventory getLeftSide();
/**
* Get the right side of this double chest.
*
* @return The right side inventory
*/
Inventory getRightSide();

2
paper-api/src/main/java/org/bukkit/inventory/EnchantingInventory.java
View file

@ -3,11 +3,13 @@ package org.bukkit.inventory;
public interface EnchantingInventory extends Inventory {
/**
* Set the item being enchanted.
*
* @param item The new item
*/
void setItem(ItemStack item);
/**
* Get the item being enchanted.
*
* @return The current item.
*/
ItemStack getItem();

6
paper-api/src/main/java/org/bukkit/inventory/FurnaceInventory.java
View file

@ -5,36 +5,42 @@ import org.bukkit.block.Furnace;
public interface FurnaceInventory extends Inventory {
/**
* Get the current item in the result slot.
*
* @return The item
*/
ItemStack getResult();
/**
* Get the current fuel.
*
* @return The item
*/
ItemStack getFuel();
/**
* Get the item currently smelting.
*
* @return The item
*/
ItemStack getSmelting();
/**
* Set the current fuel.
*
* @param stack The item
*/
void setFuel(ItemStack stack);
/**
* Set the current item in the result slot.
*
* @param stack The item
*/
void setResult(ItemStack stack);
/**
* Set the item currently smelting.
*
* @param stack The item
*/
void setSmelting(ItemStack stack);

1
paper-api/src/main/java/org/bukkit/inventory/Inventory.java
View file

@ -38,6 +38,7 @@ public interface Inventory extends Iterable<ItemStack> {
* <li>Stacks larger than the default max size for this type of inventory may not display
* correctly in the client.
* </ul>
*
* @param size The new maximum stack size for items in this inventory.
*/
public void setMaxStackSize(int size);

22
paper-api/src/main/java/org/bukkit/inventory/InventoryView.java
View file

@ -6,7 +6,7 @@ import org.bukkit.event.inventory.InventoryType;
/**
* Represents a view linking two inventories and a single player
* (whose inventory may or may not be one of the two)
*
* <p>
* Note: If you implement this interface but fail to satisfy the expected
* contracts of certain methods, there's no guarantee that the game
* will work as it should.
@ -62,18 +62,21 @@ public abstract class InventoryView {
}
/**
* Get the upper inventory involved in this transaction.
*
* @return the inventory
*/
public abstract Inventory getTopInventory();
/**
* Get the lower inventory involved in this transaction.
*
* @return the inventory
*/
public abstract Inventory getBottomInventory();
/**
* Get the player viewing.
*
* @return the player
*/
public abstract HumanEntity getPlayer();
@ -82,6 +85,7 @@ public abstract class InventoryView {
* Determine the type of inventory involved in the transaction. This indicates
* the window style being shown. It will never return PLAYER, since that is
* common to all windows.
*
* @return the inventory type
*/
public abstract InventoryType getType();
@ -91,6 +95,7 @@ public abstract class InventoryView {
* <p>
* Note: If slot ID -999 is chosen, it may be expected that the item is
* dropped on the ground. This is not required behaviour, however.
*
* @param slot The ID as returned by InventoryClickEvent.getRawSlot()
* @param item The new item to put in the slot, or null to clear it.
*/
@ -108,6 +113,7 @@ public abstract class InventoryView {
/**
* Gets one item in this inventory view by its raw slot ID.
*
* @param slot The ID as returned by InventoryClickEvent.getRawSlot()
* @return The item currently in the slot.
*/
@ -124,6 +130,7 @@ public abstract class InventoryView {
/**
* Sets the item on the cursor of one of the viewing players.
*
* @param item The item to put on the cursor, or null to remove the item on their cursor.
*/
public final void setCursor(ItemStack item) {
@ -132,6 +139,7 @@ public abstract class InventoryView {
/**
* Get the item on the cursor of one of the viewing players.
*
* @return The item on the player's cursor, or null if they aren't holding one.
*/
public final ItemStack getCursor() {
@ -144,6 +152,7 @@ public abstract class InventoryView {
* unchanged and thus be suitable for getTopInventory().getItem(); if it refers to the
* lower inventory, the output will differ from the input and be suitable for
* getBottomInventory().getItem().
*
* @param rawSlot The raw slot ID.
* @return The converted slot ID.
*/
@ -173,18 +182,29 @@ public abstract class InventoryView {
* Check the total number of slots in this view, combining the upper and lower inventories.
* Note though that it's possible for this to be greater than the sum of the two inventories
* if for example some slots are not being used.
*
* @return The total size
*/
public final int countSlots() {
return getTopInventory().getSize() + getBottomInventory().getSize();
}
/**
* Sets an extra property of this inventory if supported by that
* inventory, for example the state of a progress bar.
*
* @param prop the window property to update
* @param value the new value for the window property
* @return true if the property was updated successfully, false if the
* property is not supported by that inventory
*/
public final boolean setProperty(Property prop, int value) {
return getPlayer().setWindowProperty(prop, value);
}
/**
* Get the title of this inventory window.
*
* @return The title.
*/
public final String getTitle() {

5
paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java
View file

@ -15,6 +15,7 @@ public interface ItemFactory {
/**
* This creates a new item meta for the material.
*
* @param material The material to consider as base for the meta
* @return a new ItemMeta that could be applied to an item stack of the specified material
*/
@ -23,6 +24,7 @@ public interface ItemFactory {
/**
* This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack.
* A {@link SkullMeta} would not be valid for a sword, but a normal {@link ItemMeta} from an enchanted dirt block would.
*
* @param meta Meta to check
* @param stack Item that meta will be applied to
* @return true if the meta can be applied without losing data, false otherwise
@ -33,6 +35,7 @@ public interface ItemFactory {
/**
* This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified Material.
* A {@link SkullMeta} would not be valid for a sword, but a normal {@link ItemMeta} from an enchanted dirt block would.
*
* @param meta Meta to check
* @param material Material that meta will be applied to
* @return true if the meta can be applied without losing data, false otherwise
@ -42,6 +45,7 @@ public interface ItemFactory {
/**
* This method is used to compare two item meta data objects.
*
* @param meta1 First meta to compare, and may be null to indicate no data
* @param meta2 Second meta to compare, and may be null to indicate no data
* @return false if one of the meta has data the other does not, otherwise true
@ -51,6 +55,7 @@ public interface ItemFactory {
/**
* Returns an appropriate item meta for the specified stack.
*
* The item meta returned will always be a valid meta for a given item stack of the specified material.
* It may be a more or less specific meta, and could also be the same meta or meta type as the parameter.
* The item meta returned will also always be the most appropriate meta. <br>

1
paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java
View file

@ -118,7 +118,6 @@ public interface PlayerInventory extends Inventory {
*
* @param id the id of the item you want to clear from the inventory
* @param data the data of the item you want to clear from the inventory
*
* @return The number of items cleared
*/
public int clear(int id, int data);

2
paper-api/src/main/java/org/bukkit/material/CocoaPlant.java
View file

@ -39,6 +39,7 @@ public class CocoaPlant extends MaterialData implements Directional, Attachable
/**
* Get size of plant
*
* @return size
*/
public CocoaPlantSize getSize() {
@ -54,6 +55,7 @@ public class CocoaPlant extends MaterialData implements Directional, Attachable
/**
* Set size of plant
*
* @param sz - size of plant
*/
public void setSize(CocoaPlantSize sz) {

2
paper-api/src/main/java/org/bukkit/material/Mushroom.java
View file

@ -52,6 +52,7 @@ public class Mushroom extends MaterialData {
/**
* Checks whether a face of the block is painted.
*
* @param face The face to check.
* @return True if it is painted.
*/
@ -81,6 +82,7 @@ public class Mushroom extends MaterialData {
/**
* Set a face of the block to be painted or not. Note that due to the nature of how the data is stored,
* setting a face painted or not is not guaranteed to leave the other faces unchanged.
*
* @param face The face to paint or unpaint.
* @param painted True if you want to paint it, false if you want the pores to show.
*/

2
paper-api/src/main/java/org/bukkit/material/SpawnEgg.java
View file

@ -26,6 +26,7 @@ public class SpawnEgg extends MaterialData {
/**
* Get the type of entity this egg will spawn.
*
* @return The entity type.
*/
public EntityType getSpawnedType() {
@ -34,6 +35,7 @@ public class SpawnEgg extends MaterialData {
/**
* Set the type of entity this egg will spawn.
*
* @param type The entity type.
*/
public void setSpawnedType(EntityType type) {

2
paper-api/src/main/java/org/bukkit/material/Stairs.java
View file

@ -90,6 +90,7 @@ public class Stairs extends MaterialData implements Directional {
/**
* Test if step is inverted
*
* @return true if inverted (top half), false if normal (bottom half)
*/
public boolean isInverted() {
@ -98,6 +99,7 @@ public class Stairs extends MaterialData implements Directional {
/**
* Set step inverted state
*
* @param inv - true if step is inverted (top half), false if step is normal (bottom half)
*/
public void setInverted(boolean inv) {

2
paper-api/src/main/java/org/bukkit/material/Step.java
View file

@ -49,6 +49,7 @@ public class Step extends TexturedMaterial {
/**
* Test if step is inverted
*
* @return true if inverted (top half), false if normal (bottom half)
*/
public boolean isInverted() {
@ -57,6 +58,7 @@ public class Step extends TexturedMaterial {
/**
* Set step inverted state
*
* @param inv - true if step is inverted (top half), false if step is normal (bottom half)
*/
public void setInverted(boolean inv) {

2
paper-api/src/main/java/org/bukkit/material/TexturedMaterial.java
View file

@ -62,6 +62,7 @@ public abstract class TexturedMaterial extends MaterialData {
/**
* Get material index from data
*
* @return index of data in textures list
*/
protected int getTextureIndex() {
@ -70,6 +71,7 @@ public abstract class TexturedMaterial extends MaterialData {
/**
* Set material index
*
* @param idx - index of data in textures list
*/
protected void setTextureIndex(int idx) {

2
paper-api/src/main/java/org/bukkit/material/TrapDoor.java
View file

@ -45,6 +45,7 @@ public class TrapDoor extends SimpleAttachableMaterialData implements Openable {
/**
* Test if trapdoor is inverted
*
* @return true if inverted (top half), false if normal (bottom half)
*/
public boolean isInverted() {
@ -53,6 +54,7 @@ public class TrapDoor extends SimpleAttachableMaterialData implements Openable {
/**
* Set trapdoor inverted state
*
* @param inv - true if inverted (top half), false if normal (bottom half)
*/
public void setInverted(boolean inv) {

1
paper-api/src/main/java/org/bukkit/material/Tree.java
View file

@ -77,6 +77,7 @@ public class Tree extends MaterialData {
}
/**
* Set direction of the log
*
* @param dir - direction of end of log (BlockFace.SELF for no direction)
*/
public void setDirection(BlockFace dir) {

4
paper-api/src/main/java/org/bukkit/material/Tripwire.java
View file

@ -21,6 +21,7 @@ public class Tripwire extends MaterialData {
/**
* Test if tripwire is currently activated
*
* @return true if activated, false if not
*/
public boolean isActivated() {
@ -29,6 +30,7 @@ public class Tripwire extends MaterialData {
/**
* Set tripwire activated state
*
* @param act - true if activated, false if not
*/
public void setActivated(boolean act) {
@ -41,6 +43,7 @@ public class Tripwire extends MaterialData {
/**
* Test if object triggering this tripwire directly
*
* @return true if object activating tripwire, false if not
*/
public boolean isObjectTriggering() {
@ -49,6 +52,7 @@ public class Tripwire extends MaterialData {
/**
* Set object triggering state for this tripwire
*
* @param trig - true if object activating tripwire, false if not
*/
public void setObjectTriggering(boolean trig) {

4
paper-api/src/main/java/org/bukkit/material/TripwireHook.java
View file

@ -27,6 +27,7 @@ public class TripwireHook extends SimpleAttachableMaterialData implements Redsto
/**
* Test if tripwire is connected
*
* @return true if connected, false if not
*/
public boolean isConnected() {
@ -35,6 +36,7 @@ public class TripwireHook extends SimpleAttachableMaterialData implements Redsto
/**
* Set tripwire connection state
*
* @param connected - true if connected, false if not
*/
public void setConnected(boolean connected) {
@ -47,6 +49,7 @@ public class TripwireHook extends SimpleAttachableMaterialData implements Redsto
/**
* Test if hook is currently activated
*
* @return true if activated, false if not
*/
public boolean isActivated() {
@ -55,6 +58,7 @@ public class TripwireHook extends SimpleAttachableMaterialData implements Redsto
/**
* Set hook activated state
*
* @param act - true if activated, false if not
*/
public void setActivated(boolean act) {

2
paper-api/src/main/java/org/bukkit/material/WoodenStep.java
View file

@ -55,6 +55,7 @@ public class WoodenStep extends MaterialData {
/**
* Test if step is inverted
*
* @return true if inverted (top half), false if normal (bottom half)
*/
public boolean isInverted() {
@ -63,6 +64,7 @@ public class WoodenStep extends MaterialData {
/**
* Set step inverted state
*
* @param inv - true if step is inverted (top half), false if step is normal (bottom half)
*/
public void setInverted(boolean inv) {

2
paper-api/src/main/java/org/bukkit/metadata/FixedMetadataValue.java
View file

@ -7,7 +7,7 @@ import java.util.concurrent.Callable;
/**
* A FixedMetadataValue is a special case metadata item that contains the same value forever after initialization.
* Invalidating a FixedMetadataValue has no effect.
*
* <p>
* This class extends LazyMetadataValue for historical reasons, even though it overrides all the implementation
* methods. it is possible that in the future that the inheritance hierarchy may change.
*/

8
paper-api/src/main/java/org/bukkit/metadata/MetadataValue.java
View file

@ -13,48 +13,56 @@ public interface MetadataValue {
/**
* Attempts to convert the value of this metadata item into an int.
*
* @return the value as an int.
*/
public int asInt();
/**
* Attempts to convert the value of this metadata item into a float.
*
* @return the value as a float.
*/
public float asFloat();
/**
* Attempts to convert the value of this metadata item into a double.
*
* @return the value as a double.
*/
public double asDouble();
/**
* Attempts to convert the value of this metadata item into a long.
*
* @return the value as a long.
*/
public long asLong();
/**
* Attempts to convert the value of this metadata item into a short.
*
* @return the value as a short.
*/
public short asShort();
/**
* Attempts to convert the value of this metadata item into a byte.
*
* @return the value as a byte.
*/
public byte asByte();
/**
* Attempts to convert the value of this metadata item into a boolean.
*
* @return the value as a boolean.
*/
public boolean asBoolean();
/**
* Attempts to convert the value of this metadata item into a string.
*
* @return the value as a string.
*/
public String asString();

3
paper-api/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java
View file

@ -8,11 +8,10 @@ import org.bukkit.util.NumberConversions;
/**
* Optional base class for facilitating MetadataValue implementations.
*
* <p>
* This provides all the conversion functions for MetadataValue
* so that writing an implementation of MetadataValue is as simple
* as implementing value() and invalidate().
*
*/
public abstract class MetadataValueAdapter implements MetadataValue {
protected final WeakReference<Plugin> owningPlugin;

2
paper-api/src/main/java/org/bukkit/permissions/Permission.java
View file

@ -76,7 +76,7 @@ public class Permission {
/**
* Gets the children of this permission.
*
* <p>
* If you change this map in any form, you must call {@link #recalculatePermissibles()} to recalculate all {@link Permissible}s
*
* @return Permission children

2
paper-api/src/main/java/org/bukkit/plugin/Plugin.java
View file

@ -166,7 +166,7 @@ public interface Plugin extends TabExecutor {
/**
* Returns the name of the plugin.
*
* <p>
* This should return the bare name of the plugin and should be used for comparison.
*
* @return name of the plugin

1
paper-api/src/main/java/org/bukkit/plugin/PluginLogger.java
View file

@ -15,6 +15,7 @@ public class PluginLogger extends Logger {
/**
* Creates a new PluginLogger that extracts the name from a plugin.
*
* @param context A reference to the plugin
*/
public PluginLogger(Plugin context) {

7
paper-api/src/main/java/org/bukkit/potion/Potion.java
View file

@ -23,6 +23,7 @@ public class Potion {
* Construct a new potion of the given type. Unless the type is {@link PotionType#WATER},
* it will be level one, without extended duration. Don't use this constructor to create
* a no-effect potion other than water bottle.
*
* @param type The potion type
* @see #Potion(int)
*/
@ -61,6 +62,7 @@ public class Potion {
/**
* Create a new potion of the given type and level.
*
* @param type The type of potion.
* @param level The potion's level.
*/
@ -74,6 +76,7 @@ public class Potion {
/**
* Create a new potion of the given type and level.
*
* @param type The type of potion.
* @param level The potion's level.
* @param splash Whether it is a splash potion.
@ -87,6 +90,7 @@ public class Potion {
/**
* Create a new potion of the given type and level.
*
* @param type The type of potion.
* @param level The potion's level.
* @param splash Whether it is a splash potion.
@ -102,6 +106,7 @@ public class Potion {
/**
* Create a potion with a specific name.
*
* @param name The name index (0-63)
*/
public Potion(int name) {
@ -115,6 +120,7 @@ public class Potion {
/**
* Chain this to the constructor to make the potion a splash potion.
*
* @return The potion.
*/
public Potion splash() {
@ -124,6 +130,7 @@ public class Potion {
/**
* Chain this to the constructor to extend the potion's duration.
*
* @return The potion.
*/
public Potion extend() {

2
paper-api/src/main/java/org/bukkit/potion/PotionEffect.java
View file

@ -126,6 +126,7 @@ public class PotionEffect implements ConfigurationSerializable {
* Returns the amplifier of this effect. A higher amplifier means the potion
* effect happens more often over its duration and in some cases has more
* effect on its target.
*
* @return The effect amplifier
*/
public int getAmplifier() {
@ -135,6 +136,7 @@ public class PotionEffect implements ConfigurationSerializable {
/**
* Returns the duration (in ticks) that this effect will run for when
* applied to a {@link LivingEntity}.
*
* @return The duration of the effect
*/
public int getDuration() {

1
paper-api/src/main/java/org/bukkit/potion/PotionEffectTypeWrapper.java
View file

@ -17,6 +17,7 @@ public class PotionEffectTypeWrapper extends PotionEffectType {
/**
* Get the potion type bound to this wrapper.
*
* @return The potion effect type
*/
public PotionEffectType getType() {

5
paper-api/src/main/java/org/bukkit/util/BlockIterator.java
View file

@ -14,7 +14,6 @@ import java.util.NoSuchElementException;
/**
* This class performs ray tracing and iterates along blocks on a line
*/
public class BlockIterator implements Iterator<Block> {
private final World world;
@ -49,7 +48,6 @@ public class BlockIterator implements Iterator<Block> {
* @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit
*
*/
public BlockIterator(World world, Vector start, Vector direction, double yOffset, int maxDistance) {
this.world = world;
this.maxDistance = maxDistance;
@ -224,9 +222,7 @@ public class BlockIterator implements Iterator<Block> {
* @param loc The location for the start of the ray trace
* @param yOffset The trace begins vertically offset from the start vector by this value
* @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit
*
*/
public BlockIterator(Location loc, double yOffset, int maxDistance) {
this(loc.getWorld(), loc.toVector(), loc.getDirection(), yOffset, maxDistance);
}
@ -257,7 +253,6 @@ public class BlockIterator implements Iterator<Block> {
*
* @param entity Information from the entity is used to set up the trace
* @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit
*
*/
public BlockIterator(LivingEntity entity, int maxDistance) {

3
paper-api/src/main/java/org/bukkit/util/ChatPaginator.java
View file

@ -19,6 +19,7 @@ public class ChatPaginator {
/**
* Breaks a raw string up into pages using the default width and height.
*
* @param unpaginatedString The raw string to break.
* @param pageNumber The page number to fetch.
* @return A single chat page.
@ -29,6 +30,7 @@ public class ChatPaginator {
/**
* Breaks a raw string up into pages using a provided width and height.
*
* @param unpaginatedString The raw string to break.
* @param pageNumber The page number to fetch.
* @param lineLength The desired width of a chat line.
@ -51,6 +53,7 @@ public class ChatPaginator {
/**
* Breaks a raw string up into a series of lines. Words are wrapped using spaces as decimeters and the newline
* character is respected.
*
* @param rawString The raw string to break.
* @param lineLength The length of a line of text.
* @return An array of word-wrapped lines.