Add more sign Javadocs

This commit is contained in:
Daniel Saukel 2020-01-29 19:08:12 +01:00
parent a817ba41ba
commit c20e090914
5 changed files with 79 additions and 4 deletions

View File

@ -21,7 +21,8 @@ import org.bukkit.block.Sign;
import org.bukkit.entity.Player;
/**
* A sign that performs a specific action every time it is triggered.
* A sign that performs a specific action every time it is triggered. It can have, but typically does not have a state. Consider using {@link Deactivatable) for
* sign that change themselves when they are triggered.
* <p>
* For example, a classes sign with the default interact trigger sets your class every time you punch it.
*
@ -33,10 +34,31 @@ public abstract class Button extends AbstractDSign {
super(api, sign, lines, gameWorld);
}
/**
* When the sign is triggered without one particular player being the cause.
* <p>
* <b>Note that the default implementation of {@link #push(org.bukkit.entity.Player)} assumes that the sign does not need player specific behavior and
* simply calls this method, while the default implementation of this method assumes that the sign should perform {@link #push(org.bukkit.entity.Player)}
* for each player in the game world. This leaves a button sign with a stackoverflow if not one of both methods at least is overriden. Consider using a
* {@link Passive} sign instead if you need a sign that simply marks places and ignores being triggered.</b>
*/
public void push() {
getGameWorld().getPlayers().forEach(p -> push(p.getPlayer()));
}
/**
* When the sign is triggered.
* <p>
* This is the default {@link #trigger(org.bukkit.entity.Player)} behavior.
* <p>
* <b>Note that the default implementation of this method assumes that the sign does not need player specific behavior and simply calls {@link #push()},
* while the default implementation of {@link #push()} assumes that the sign should perform {@link #push(org.bukkit.entity.Player)} for each player in the
* game world. This leaves a button sign with a stackoverflow if not one of both methods at least is overriden. Consider using a {@link Passive} sign
* instead if you need a sign that simply marks places and ignores being triggered.</b>
*
* @param player the player who triggered the sign
* @return if the action is done successfully
*/
public boolean push(Player player) {
push();
return true;
@ -68,7 +90,7 @@ public abstract class Button extends AbstractDSign {
/**
* This is the same as {@link #push(org.bukkit.entity.Player)}.
*
* @param player the player
* @param player the player who triggered the sign or null if no one in particular triggered it
*/
@Override
public void trigger(Player player) {

View File

@ -23,7 +23,7 @@ import org.bukkit.entity.Player;
/**
* A {@link DungeonSign} that changes its state when triggered.
*
*
* @author Daniel Saukel
*/
public abstract class Deactivatable extends AbstractDSign {
@ -35,26 +35,61 @@ public abstract class Deactivatable extends AbstractDSign {
super(api, sign, lines, gameWorld);
}
/**
* Sets the state to active.
* <p>
* This might not be meaningful if the sign uses {@link #activate(org.bukkit.entity.Player)}.
*/
public void activate() {
active = true;
}
/**
* Sets the state to active for the given player.
*
* @param player the player
* @return if the action was successful
*/
public boolean activate(Player player) {
return playersActivated.add(player);
}
/**
* Sets the state to inactive.
* <p>
* This might not be meaningful if the sign uses {@link #deactivate(org.bukkit.entity.Player)}.
*/
public void deactivate() {
active = false;
}
/**
* Sets the state to inactive for the given player.
*
* @param player the player
* @return if the action was successful
*/
public boolean deactivate(Player player) {
return playersActivated.remove(player);
}
/**
* Returns if the sign is currently in its activated state.
* <p>
* This might not be meaningful if the sign uses {@link #isActive(org.bukkit.entity.Player)}.
*
* @return if the sign is currently in its activated state
*/
public boolean isActive() {
return active;
}
/**
* Returns if the sign is activated for the given player.
*
* @param player the player
* @return if the sign is activated for the given player
*/
public boolean isActive(Player player) {
return playersActivated.contains(player);
}

View File

@ -131,7 +131,7 @@ public interface DungeonSign {
/**
* Triggers the sign. The effects are defined by the implementation.
*
* @param player the player that triggered the sign or null
* @param player the player who triggered the sign or null if no one in particular triggered it
*/
void trigger(Player player);
@ -142,6 +142,9 @@ public interface DungeonSign {
/**
* Sets the sign to air if it is not erroneous and if its type requires this.
* <p>
* Signs are usually to be set to air upon initialization, but this is not done automatically because some signs need different behavior. Script signs for
* example are not set to air because this would override whatever a block sign in its script does.
*
* @return if the sign type was set to air
*/
@ -149,6 +152,8 @@ public interface DungeonSign {
/**
* Returns if the sign is valid.
* <p>
* A sign is invalid when it lacks needed parameters or if illegal arguments have been entered.
*
* @return if the sign is valid
*/

View File

@ -30,10 +30,18 @@ public abstract class Passive extends AbstractDSign {
super(api, sign, lines, gameWorld);
}
/**
* Does nothing.
*/
@Override
public final void update() {
}
/**
* Does nothing.
*
* @param player unused
*/
@Override
public final void trigger(Player player) {
}

View File

@ -33,6 +33,11 @@ public abstract class Rocker extends Deactivatable {
super(api, sign, lines, gameWorld);
}
/**
* Activates the sign if it is not yet active and deactivates it if it is already active.
*
* @param player the player who triggered the sign or null if no one in particular triggered it
*/
@Override
public void trigger(Player player) {
if (!isActive()) {