SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
paper-api/src/main/java/org/bukkit/conversations/Conversation.java
View File

@@ -8,23 +8,29 @@ import java.util.List;
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.
* 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.
* 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.
* 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.
* 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.
* You should not construct a conversation manually. Instead, use the {@link
* ConversationFactory} for access to all available options.
*/
public class Conversation {
@@ -55,7 +61,8 @@ public class 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.
* @param initialSessionData Any initial values to put in the conversation context sessionData map.
* @param initialSessionData Any initial values to put in the conversation
* context sessionData map.
*/
public Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<Object, Object> initialSessionData) {
this.firstPrompt = firstPrompt;
@@ -77,8 +84,9 @@ 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.
* 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.
*/
@@ -87,8 +95,9 @@ 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.
* 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.
*/
@@ -97,8 +106,9 @@ 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.
* 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.
*/
@@ -107,8 +117,9 @@ 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.
* 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.
*/
@@ -117,7 +128,8 @@ public class Conversation {
}
/**
* Gets the {@link ConversationPrefix} that prepends all output from this conversation.
* Gets the {@link ConversationPrefix} that prepends all output from this
* conversation.
*
* @return The ConversationPrefix in use.
*/
@@ -126,7 +138,8 @@ public class Conversation {
}
/**
* Sets the {@link ConversationPrefix} that prepends all output from this conversation.
* Sets the {@link ConversationPrefix} that prepends all output from this
* conversation.
*
* @param prefix The ConversationPrefix to use.
*/
@@ -163,7 +176,8 @@ public class Conversation {
}
/**
* Displays the first prompt of this conversation and begins redirecting the user's chat responses.
* Displays the first prompt of this conversation and begins redirecting
* the user's chat responses.
*/
public void begin() {
if (currentPrompt == null) {
@@ -175,6 +189,7 @@ public class Conversation {
/**
* Returns Returns the current state of the conversation.
*
* @return The current state of the conversation.
*/
public ConversationState getState() {
@@ -188,8 +203,9 @@ public class Conversation {
}
/**
* Passes player input into the current prompt. The next prompt (as determined by the current prompt) is then
* displayed to the user.
* Passes player input into the current prompt. The next prompt (as
* determined by the current prompt) is then displayed to the user.
*
* @param input The user's chat text.
*/
public void acceptInput(String input) {
@@ -216,6 +232,7 @@ public class Conversation {
/**
* Adds a {@link ConversationAbandonedListener}.
*
* @param listener The listener to add.
*/
public synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener) {
@@ -224,6 +241,7 @@ public class Conversation {
/**
* Removes a {@link ConversationAbandonedListener}.
*
* @param listener The listener to remove.
*/
public synchronized void removeConversationAbandonedListener(ConversationAbandonedListener listener) {
@@ -231,14 +249,17 @@ public class Conversation {
}
/**
* Abandons and resets the current conversation. Restores the user's normal chat behavior.
* Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*/
public void abandon() {
abandon(new ConversationAbandonedEvent(this, new ManuallyAbandonedConversationCanceller()));
}
/**
* Abandons and resets the current conversation. Restores the user's normal chat behavior.
* Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*
* @param details Details about why the conversation was abandoned
*/
public synchronized void abandon(ConversationAbandonedEvent details) {
@@ -253,7 +274,8 @@ public class Conversation {
}
/**
* Displays the next user prompt and abandons the conversation if the next prompt is null.
* Displays the next user prompt and abandons the conversation if the next
* prompt is null.
*/
public void outputNextPrompt() {
if (currentPrompt == null) {