Add more sign Javadocs

api/src/main/java/de/erethon/dungeonsxl/api/sign/Button.java

@@ -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) {

api/src/main/java/de/erethon/dungeonsxl/api/sign/Deactivatable.java

@@ -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);
     }

api/src/main/java/de/erethon/dungeonsxl/api/sign/DungeonSign.java

@@ -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
      */

api/src/main/java/de/erethon/dungeonsxl/api/sign/Passive.java

@@ -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) {
     }

api/src/main/java/de/erethon/dungeonsxl/api/sign/Rocker.java

@@ -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()) {