Add consistent comments to synchronization blocks.

src/org/apollo/game/sync/block/AnimationBlock.java

@@ -3,14 +3,14 @@ package org.apollo.game.sync.block;
 import org.apollo.game.model.Animation;
 
 /**
- * The animation {@link SynchronizationBlock}.
+ * The animation {@link SynchronizationBlock}. Both npcs and players can utilise this block.
  * 
  * @author Graham
  */
 public final class AnimationBlock extends SynchronizationBlock {
 
 	/**
-	 * The {@link Animation}.
+	 * The animation.
 	 */
 	private final Animation animation;
 

src/org/apollo/game/sync/block/AppearanceBlock.java

@@ -4,7 +4,7 @@ import org.apollo.game.model.Appearance;
 import org.apollo.game.model.Inventory;
 
 /**
- * The appearance {@link SynchronizationBlock}.
+ * The appearance {@link SynchronizationBlock}. Only players can utilise this block.
  * 
  * @author Graham
  */
@@ -51,14 +51,32 @@ public final class AppearanceBlock extends SynchronizationBlock {
 	private final int skill;
 
 	/**
-	 * Creates the appearance block.
+	 * Creates the appearance block. Assumes that the player is not appearing as an npc.
 	 * 
-	 * @param name The player's username.
+	 * @param name The player's username, encoded to base 37.
-	 * @param appearance The appearance.
+	 * @param appearance The {@link Appearance}.
 	 * @param combat The player's combat.
 	 * @param skill The player's skill, or 0 if showing the combat level.
 	 * @param equipment The player's equipment.
-	 * @param npcId The npc id of the player, if they are appearing as an npc (otherwise {@code -1}).
+	 * @param prayerIcon The prayer icon id of this player.
+	 * @param headIcon The head icon id of this player.
+	 */
+	AppearanceBlock(long name, Appearance appearance, int combat, int skill, Inventory equipment, int prayerIcon,
+			int headIcon) {
+		this(name, appearance, combat, skill, equipment, prayerIcon, headIcon, -1);
+	}
+
+	/**
+	 * Creates the appearance block.
+	 * 
+	 * @param name The player's username, encoded to base 37.
+	 * @param appearance The {@link Appearance}.
+	 * @param combat The player's combat.
+	 * @param skill The player's skill, or 0 if showing the combat level.
+	 * @param equipment The player's equipment.
+	 * @param prayerIcon The prayer icon id of this player.
+	 * @param headIcon The head icon id of this player.
+	 * @param npcId The npc id of the player, if they are appearing as an npc, (otherwise {@code -1}).
 	 */
 	AppearanceBlock(long name, Appearance appearance, int combat, int skill, Inventory equipment, int prayerIcon,
 			int headIcon, int npcId) {
@@ -82,7 +100,7 @@ public final class AppearanceBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the player's appearance.
+	 * Gets the player's {@link Appearance}.
 	 * 
 	 * @return The player's appearance.
 	 */
@@ -127,7 +145,7 @@ public final class AppearanceBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the npc id the player is appearing as, if any.
+	 * Gets the npc id the player is appearing as, or {@code -1} if the player is not appearing as one.
 	 * 
 	 * @return The npc id.
 	 */

src/org/apollo/game/sync/block/ChatBlock.java

@@ -4,7 +4,7 @@ import org.apollo.game.event.impl.ChatEvent;
 import org.apollo.game.model.settings.PrivilegeLevel;
 
 /**
- * The chat {@link SynchronizationBlock}.
+ * The chat {@link SynchronizationBlock}. Only players can utilise this block.
  * 
  * @author Graham
  */
@@ -22,6 +22,9 @@ public final class ChatBlock extends SynchronizationBlock {
 
 	/**
 	 * Creates the chat block.
+	 * 
+	 * @param privilegeLevel The {@link PrivilegeLevel} of the player who said the message.
+	 * @param chatEvent The {@link ChatEvent}.
 	 */
 	ChatBlock(PrivilegeLevel privilegeLevel, ChatEvent chatEvent) {
 		this.privilegeLevel = privilegeLevel;
@@ -47,7 +50,7 @@ public final class ChatBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the privilege level of the player who said the message.
+	 * Gets the {@link PrivilegeLevel} of the player who said the message.
 	 * 
 	 * @return The privilege level.
 	 */

src/org/apollo/game/sync/block/ForceChatBlock.java

@@ -1,13 +1,12 @@
 package org.apollo.game.sync.block;
 
 /**
- * The Force Chat {@link SynchronizationBlock}. This is a block that can be implemented in both player and npc
+ * The force chat {@link SynchronizationBlock}. Both players and npcs can utilise this block. It is not possible to add
- * synchronization tasks, and will cause the mob to shout the specified text. It is not possible to add colour or effect
+ * colour or effect (e.g. wave or scroll) to this block.
- * (e.g. wave or scroll) to this block.
  * 
  * @author Major
  */
-public class ForceChatBlock extends SynchronizationBlock {
+public final class ForceChatBlock extends SynchronizationBlock {
 
 	/**
 	 * The chat text.
@@ -15,9 +14,9 @@ public class ForceChatBlock extends SynchronizationBlock {
 	private final String message;
 
 	/**
-	 * Creates a new force chat [@link SynchronizationBlock}.
+	 * Creates the force chat block.
 	 * 
-	 * @param message The message the mob will say.
+	 * @param message The message.
 	 */
 	public ForceChatBlock(String message) {
 		this.message = message;

src/org/apollo/game/sync/block/ForceMovementBlock.java

@@ -4,15 +4,15 @@ import org.apollo.game.model.Direction;
 import org.apollo.game.model.Position;
 
 /**
- * The Force Movement {@link SynchronizationBlock}.
+ * The Force Movement {@link SynchronizationBlock}. Only players can utilise this block.
- * 
+ * <p>
- * @note This block is used to force a player to walk to a set location. The player can then perform an action (e.g. an
+ * Note: This block is used to force a player to walk to a set location. The player can then perform an action (e.g. an
- *       animation), as used in the Agility skill, hence this block earning the name 'Asynchronous Animation/Walking',
+ * animation), as used in the Agility skill, hence this block earning the name 'Asynchronous Animation/Walking',
- *       although the action is not restricted to animations.
+ * although the action is not restricted to animations.
  * 
  * @author Major
  */
-public class ForceMovementBlock extends SynchronizationBlock {
+public final class ForceMovementBlock extends SynchronizationBlock {
 
 	/**
 	 * The direction the player is moving.
@@ -30,22 +30,22 @@ public class ForceMovementBlock extends SynchronizationBlock {
 	private final Position initialPosition;
 
 	/**
-	 * The length of time (in game pulses) the player's movement along the X axis will last.
+	 * The length of time (in game pulses) the player's movement along the X-axis will last.
 	 */
 	private final int travelDurationX;
 
 	/**
-	 * The length of time (in game pulses) the player's movement along the Y axis will last.
+	 * The length of time (in game pulses) the player's movement along the Y-axis will last.
 	 */
 	private final int travelDurationY;
 
 	/**
-	 * Creates a new Force Movement block.
+	 * Creates a new force movement block.
 	 * 
 	 * @param initialPosition The initial {@link Position} of the player.
 	 * @param finalPosition The final {@link Position} of the player
-	 * @param travelDurationX The length of time (in game pulses) the player's movement along the X axis will last.
+	 * @param travelDurationX The length of time (in game pulses) the player's movement along the X-axis will last.
-	 * @param travelDurationY The length of time (in game pulses) the player's movement along the Y axis will last.
+	 * @param travelDurationY The length of time (in game pulses) the player's movement along the Y-axis will last.
 	 * @param direction The direction the player should move.
 	 */
 	ForceMovementBlock(Position initialPosition, Position finalPosition, int travelDurationX, int travelDurationY,
@@ -58,7 +58,7 @@ public class ForceMovementBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the direction the player should move.
+	 * Gets the {@link Direction} the player should move.
 	 * 
 	 * @return The direction.
 	 */
@@ -66,16 +66,6 @@ public class ForceMovementBlock extends SynchronizationBlock {
 		return direction;
 	}
 
-	/**
-	 * Gets the final position. This shouldn't be used to get the initial X and Y coordinates, see {@link #getFinalX()}
-	 * and {@link #getFinalY()}.
-	 * 
-	 * @return The final {@link Position}.
-	 */
-	public Position getFinalPosition() {
-		return finalPosition;
-	}
-
 	/**
 	 * Gets the X coordinate of the final {@link Position}.
 	 * 
@@ -94,16 +84,6 @@ public class ForceMovementBlock extends SynchronizationBlock {
 		return finalPosition.getY();
 	}
 
-	/**
-	 * Gets the initial position. This shouldn't be used to get the initial X and Y coordinates, see
-	 * {@link #getInitialX()} and {@link #getInitialY()}.
-	 * 
-	 * @return The initial {@link Position}.
-	 */
-	public Position getInitialPosition() {
-		return initialPosition;
-	}
-
 	/**
 	 * Gets the X coordinate of the initial {@link Position}.
 	 * 
@@ -123,7 +103,7 @@ public class ForceMovementBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the length of time (in game pulses) the player's movement along the Y axis will last.
+	 * Gets the length of time (in game pulses) the player's movement along the X-axis will last.
 	 * 
 	 * @return The time period.
 	 */
@@ -132,7 +112,7 @@ public class ForceMovementBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the length of time (in game pulses) the player's movement along the Y axis will last.
+	 * Gets the length of time (in game pulses) the player's movement along the Y-axis will last.
 	 * 
 	 * @return The time period.
 	 */

src/org/apollo/game/sync/block/GraphicBlock.java

@@ -3,7 +3,7 @@ package org.apollo.game.sync.block;
 import org.apollo.game.model.Graphic;
 
 /**
- * The graphic {@link SynchronizationBlock}.
+ * The graphic {@link SynchronizationBlock}. Both players and npcs can utilise this block.
  * 
  * @author Graham
  */
@@ -24,7 +24,7 @@ public final class GraphicBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the graphic.
+	 * Gets the {@link Graphic}.
 	 * 
 	 * @return The graphic.
 	 */

src/org/apollo/game/sync/block/HitUpdateBlock.java

@@ -1,11 +1,11 @@
 package org.apollo.game.sync.block;
 
 /**
- * The hit update {@link SynchronizationBlock}. Both npcs and players can implement this block.
+ * The hit update {@link SynchronizationBlock}. Both npcs and players can utilise this block.
  * 
  * @author Major
  */
-public class HitUpdateBlock extends SynchronizationBlock {
+public final class HitUpdateBlock extends SynchronizationBlock {
 
 	/**
 	 * The mob's current health.
@@ -28,7 +28,7 @@ public class HitUpdateBlock extends SynchronizationBlock {
 	private final int type;
 
 	/**
-	 * Creates a new Hit Update block.
+	 * Creates the hit update block.
 	 * 
 	 * @param damage The damage dealt by the hit.
 	 * @param type The type of hit.

src/org/apollo/game/sync/block/InteractingMobBlock.java

@@ -1,14 +1,11 @@
 package org.apollo.game.sync.block;
 
 /**
- * The interacting mob {@link SynchronizationBlock}.
+ * The interacting mob {@link SynchronizationBlock}. Both players and npcs can utilise this block.
- * <p>
- * Note: As all Apollo events should be immutable to avoid concurrency issues, this uses the index of the mob rather
- * than the actual mob. This should not be changed.
  * 
  * @author Major
  */
-public class InteractingMobBlock extends SynchronizationBlock {
+public final class InteractingMobBlock extends SynchronizationBlock {
 
 	/**
 	 * The index of the mob.

src/org/apollo/game/sync/block/SecondaryHitUpdateBlock.java

@@ -2,12 +2,11 @@ package org.apollo.game.sync.block;
 
 /**
  * The secondary hit update {@link SynchronizationBlock}. This is used for when multiple attacks happen at once (for
- * example, the dragon-dagger special attack). This block can be implemented by both players and npcs.
+ * example, the dragon-dagger special attack). Both players and npcs can utilise this block.
- * 
  * 
  * @author Major
  */
-public class SecondaryHitUpdateBlock extends SynchronizationBlock {
+public final class SecondaryHitUpdateBlock extends SynchronizationBlock {
 
 	/**
 	 * The mob's current health.

src/org/apollo/game/sync/block/SynchronizationBlock.java

@@ -18,7 +18,7 @@ import org.apollo.game.sync.seg.SynchronizationSegment;
 public abstract class SynchronizationBlock {
 
 	/**
-	 * Creates an animation block with the specified animation.
+	 * Creates an {@link AnimationBlock} with the specified animation.
 	 * 
 	 * @param animation The animation.
 	 * @return The animation block.
@@ -28,7 +28,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates an appearance block for the specified player.
+	 * Creates an {@link AppearanceBlock} for the specified player.
 	 * 
 	 * @param player The player.
 	 * @return The appearance block.
@@ -40,7 +40,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a chat block for the specified player.
+	 * Creates a {@link ChatBlock} for the specified player.
 	 * 
 	 * @param player The player.
 	 * @param chatEvent The chat event.
@@ -51,7 +51,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a new force chat block with the specified message.
+	 * Creates a {@link ForceChatBlock} with the specified message.
 	 * 
 	 * @param message The message.
 	 * @return The force chat block.
@@ -61,13 +61,13 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a new force movement block with the specified parameters.
+	 * Creates a {@link ForceMovement} block with the specified parameters.
 	 * 
 	 * @param initialPosition The initial {@link Position} of the player.
-	 * @param finalPosition The final {@link Position} of the player
+	 * @param finalPosition The final position of the player
 	 * @param travelDurationX The length of time (in game pulses) the player's movement along the X axis will last.
 	 * @param travelDurationY The length of time (in game pulses) the player's movement along the Y axis will last.
-	 * @param direction The direction the player should move.
+	 * @param direction The {@link Direction} the player should move.
 	 * @return The force movement block.
 	 */
 	public static SynchronizationBlock createForceMovementBlock(Position initialPosition, Position finalPosition,
@@ -76,7 +76,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a graphic block with the specified graphic.
+	 * Creates a {@link GraphicBlock} with the specified graphic.
 	 * 
 	 * @param graphic The graphic.
 	 * @return The graphic block.
@@ -86,7 +86,8 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a new hit or secondary hit update block
+	 * Creates a {@link HitUpdateBlock} or {@link SecondaryHitUpdateBlock}, depending on the value of the
+	 * {@code secondary} flag.
 	 * 
 	 * @param damage The damage dealt by the hit.
 	 * @param type The type of hit.
@@ -102,7 +103,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates an interacting mob block with the specified index.
+	 * Creates an {@link InteractingMobBlock} with the specified index.
 	 * 
 	 * @param index The index of the mob being interacted with.
 	 * @return The interacting mob block.
@@ -112,7 +113,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a transform block with the specified id.
+	 * Creates a {@link TransformBlock} with the specified id.
 	 * 
 	 * @param id The id.
 	 * @return The transform block.
@@ -122,7 +123,7 @@ public abstract class SynchronizationBlock {
 	}
 
 	/**
-	 * Creates a turn to position block with the specified position.
+	 * Creates a {@link TurnToPositionBlock} with the specified {@link Position}.
 	 * 
 	 * @param position The position.
 	 * @return The turn to position block.

src/org/apollo/game/sync/block/SynchronizationBlockSet.java

@@ -22,8 +22,7 @@ public final class SynchronizationBlockSet implements Cloneable {
 	 */
 	public void add(SynchronizationBlock block) {
 		Class<? extends SynchronizationBlock> clazz = block.getClass();
-		blocks.put(clazz, block); // this will overwrite old updates. best thing
+		blocks.put(clazz, block);
-									// to do?
 	}
 
 	/**
@@ -41,7 +40,7 @@ public final class SynchronizationBlockSet implements Cloneable {
 	}
 
 	/**
-	 * Checks if this set contains the specified block.
+	 * Checks if this set contains the specified {@link SynchronizationBlock}.
 	 * 
 	 * @param clazz The block's class.
 	 * @return {@code true} if so, {@code false} if not.
@@ -51,7 +50,7 @@ public final class SynchronizationBlockSet implements Cloneable {
 	}
 
 	/**
-	 * Gets a block.
+	 * Gets a {@link SynchronizationBlock} from this set.
 	 * 
 	 * @param <T> The type of block.
 	 * @param clazz The block's class.
@@ -63,18 +62,19 @@ public final class SynchronizationBlockSet implements Cloneable {
 	}
 
 	/**
-	 * Removes a block.
+	 * Removes a {@link SynchronizationBlock} from this set.
 	 * 
 	 * @param clazz The block's class.
 	 */
-	public void remove(Class<? extends SynchronizationBlock> clazz) {
+	@SuppressWarnings("unchecked")
-		blocks.remove(clazz);
+	public <T extends SynchronizationBlock> T remove(Class<? extends SynchronizationBlock> clazz) {
+		return (T) blocks.remove(clazz);
 	}
 
 	/**
-	 * Gets the size of the set.
+	 * Gets the size of this set.
 	 * 
-	 * @return The size of the set.
+	 * @return The size.
 	 */
 	public int size() {
 		return blocks.size();

src/org/apollo/game/sync/block/TransformBlock.java

@@ -1,15 +1,14 @@
 package org.apollo.game.sync.block;
 
 /**
- * The transform {@link SynchronizationBlock}. This is an npc-only block that updates the npc's definition in the
+ * The transform {@link SynchronizationBlock}. Only npcs can utilise this block.
- * client, and thus its animations, size, etc.
  * 
  * @author Major
  */
 public final class TransformBlock extends SynchronizationBlock {
 
 	/**
-	 * The new id.
+	 * The id to transform to.
 	 */
 	private final int id;
 
@@ -23,7 +22,7 @@ public final class TransformBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the id.
+	 * Gets the id of the npc to transform into.
 	 * 
 	 * @return The id.
 	 */

src/org/apollo/game/sync/block/TurnToPositionBlock.java

@@ -3,7 +3,7 @@ package org.apollo.game.sync.block;
 import org.apollo.game.model.Position;
 
 /**
- * The turn to position {@link SynchronizationBlock}.
+ * The turn to position {@link SynchronizationBlock}. Both players and npcs can utilise this block.
  * 
  * @author Graham
  */
@@ -24,7 +24,7 @@ public final class TurnToPositionBlock extends SynchronizationBlock {
 	}
 
 	/**
-	 * Gets the position to turn to.
+	 * Gets the {@link Position} to turn to.
 	 * 
 	 * @return The position to turn to.
 	 */