Add a lot of comments to the view classes and remove a deprecated method.

forge-gui/src/main/java/forge/view/Cache.java

@@ -5,28 +5,63 @@ import java.util.Map;
 
 import com.google.common.collect.Maps;
 
+/**
+ * Implementation of a two-way cache, containing bidirectional mappings from
+ * keys of type {@code K} to values of type {@code V}.
+ * 
+ * Keys and values are checked for equality using the
+ * {@link Object#equals(Object)} method.
+ * 
+ * @author elcnesh
+ *
+ * @param <K>
+ *            the type of this Cache's keys.
+ * @param <V>
+ *            the type of this Cache's values.
+ */
 public class Cache<K, V> {
 
     private final Map<K, V> cache;
     private final Map<V, K> inverseCache;
+
+    /**
+     * Create a new, empty Cache instance.
+     */
     public Cache() {
         this.cache = Maps.newHashMap();
         this.inverseCache = Maps.newHashMap();
     }
 
+    /**
+     * @param key
+     *            a key.
+     * @return {@code true} if and only if this Cache contains the specified
+     *         key.
+     */
     public boolean containsKey(final K key) {
         return cache.containsKey(key);
     }
 
     /**
+     * Get the value associated to a key.
+     * 
      * @param key
-     * @return
+     *            a key.
-     * @see java.util.Map#get(java.lang.Object)
+     * @return the value associated to key, or {@code null} if no such value
+     *         exists.
      */
     public V get(final K key) {
         return cache.get(key);
     }
 
+    /**
+     * Get the key associated to a value.
+     * 
+     * @param value
+     *            a value.
+     * @return the key associated to value, or {@code null} if no such key
+     *         exists.
+     */
     public K getKey(final V value) {
         return inverseCache.get(value);
     }
@@ -36,7 +71,8 @@ public class Cache<K, V> {
      * method.
      * 
      * @param value
-     * @return a value equal to value, if such a value is present in the Cache.
+     * @return a value equal to value, if such a value is present in the Cache;
+     *         {@code null} otherwise.
      */
     public synchronized V getValue(final V value) {
         for (final V currentValue : inverseCache.keySet()) {
@@ -48,9 +84,17 @@ public class Cache<K, V> {
     }
 
     /**
+     * Add a mapping to this Cache.
+     * 
+     * If either argument is {@code null}, this method silently returns.
+     * Otherwise, any existing mapping from the provided key to the provided
+     * value is removed, as well as its inverse. After that, the provided
+     * mapping and its inverse are added to this Cache.
+     * 
      * @param key
+     *            the key of the new mapping.
      * @param value
-     * @return
+     *            the value to map to.
      * @see java.util.Map#put(java.lang.Object, java.lang.Object)
      */
     public void put(final K key, final V value) {
@@ -70,6 +114,13 @@ public class Cache<K, V> {
         }
     }
 
+    /**
+     * Clear all the mappings in this Cache, except for any key that exists in
+     * the argument.
+     * 
+     * @param keys
+     *            the keys to retain.
+     */
     public synchronized void retainAllKeys(final Collection<K> keys) {
         cache.keySet().retainAll(keys);
         inverseCache.values().retainAll(keys);

forge-gui/src/main/java/forge/view/CardView.java

@@ -24,6 +24,14 @@ import forge.card.mana.ManaCost;
 import forge.game.card.CounterType;
 import forge.game.zone.ZoneType;
 
+/**
+ * Representation of a {@link forge.game.card.Card}, containing only the
+ * information relevant to a user interface.
+ * 
+ * Conversion from and to Cards happens through {@link LocalGameView}.
+ * 
+ * @author elcnesh
+ */
 public class CardView extends GameEntityView {
 
     private static final List<Integer> randomInts = Lists.newArrayListWithCapacity(1000);

forge-gui/src/main/java/forge/view/CombatView.java

@@ -9,6 +9,14 @@ import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
 import com.google.common.collect.Sets;
 
+/**
+ * Representation of a {@link forge.game.combat.Combat}, containing only the
+ * information relevant to a user interface.
+ * 
+ * Conversion from and to Combat happens through {@link LocalGameView}.
+ * 
+ * @author elcnesh
+ */
 public class CombatView {
 
     private Map<CardView, GameEntityView> attackersWithDefenders = Maps.newHashMap();

forge-gui/src/main/java/forge/view/GameEntityView.java

@@ -1,5 +1,12 @@
 package forge.view;
 
+/**
+ * Representation of a {@link forge.game.GameEntity}. Contains no methods, but
+ * {@link toString} may be assumed to be overridden in subclasses to provide a
+ * user-friendly string representation of the object.
+ * 
+ * @author elcnesh
+ */
 public abstract class GameEntityView {
 
 }

forge-gui/src/main/java/forge/view/IGameView.java

@@ -4,22 +4,29 @@ import java.util.List;
 import java.util.Observer;
 
 import forge.LobbyPlayer;
+import forge.card.MagicColor;
 import forge.deck.Deck;
+import forge.game.GameLog;
 import forge.game.GameLogEntry;
 import forge.game.GameLogEntryType;
 import forge.game.GameOutcome;
 import forge.game.GameType;
 import forge.game.phase.PhaseType;
-import forge.game.player.RegisteredPlayer;
+import forge.match.input.Input;
+import forge.match.input.InputConfirm;
 import forge.util.ITriggerEvent;
 
+/**
+ * Interface providing access to a game from a client. The access is assumed to
+ * be based on a single player.
+ * 
+ * @author elcnesh
+ */
 public interface IGameView {
 
-    public abstract boolean isCommander();
-
-    public abstract GameType getGameType();
-
     // Game-related methods
+    public abstract boolean isCommander();
+    public abstract GameType getGameType();
     public abstract int getTurnNumber();
     public abstract boolean isCommandZoneNeeded();
     public abstract boolean isWinner(LobbyPlayer p);
@@ -44,42 +51,184 @@ public interface IGameView {
 
     public abstract void subscribeToEvents(Object subscriber);
 
+    /**
+     * Get the game's current combat.
+     * 
+     * @return a representation of the combat, or {@code null} if there is
+     *         currently no ongoing combat.
+     */
     public abstract CombatView getCombat();
 
+    /**
+     * Add an observer to the game log.
+     * 
+     * @param o
+     *            the {@link Observer} to be sent log updates.
+     * @see GameLog
+     */
     public abstract void addLogObserver(Observer o);
+
+    /**
+     * Get all log entries up to a certain level.
+     * 
+     * @param maxLogLevel
+     *            the maximum {@link GameLogEntryType} of log entries to return.
+     * @return a list of {@link GameLogEntry}.
+     * @see GameLog
+     * @see GameLogEntry
+     * @see GameLogEntryType
+     */
     public abstract List<GameLogEntry> getLogEntries(GameLogEntryType maxLogLevel);
+
+    /**
+     * Get all log entries of a certain level.
+     * 
+     * @param logLevel
+     *            the {@link GameLogEntryType} of log entries to return.
+     * @return a list of {@link GameLogEntry}, each of which is of type
+     *         logLevel.
+     * @see GameLog
+     * @see GameLogEntry
+     * @see GameLogEntryType
+     */
     public abstract List<GameLogEntry> getLogEntriesExact(GameLogEntryType logLevel);
 
     // Input controls
+    /**
+     * @return {@code true} if and only if the last action performed by this
+     *         player can be undone.
+     */
     public abstract boolean canUndoLastAction();
+
+    /**
+     * Try to undo the last action performed by this player.
+     * 
+     * @return {@code true} if and only if the action was successfully reverted.
+     * @see IGameView#canUndoLastAction()
+     */
     public abstract boolean tryUndoLastAction();
 
+    /**
+     * Have this player perform the action currently associated with pressing
+     * the "OK" button.
+     */
     public abstract void selectButtonOk();
+
+    /**
+     * Have this player perform the action currently associated with pressing
+     * the "Cancel" button.
+     */
     public abstract void selectButtonCancel();
+
+    /**
+     * Have this player press the "OK" button if and only if the top
+     * {@link Input} is an instance of {@link InputConfirm}.
+     */
     public abstract void confirm();
+
+    /**
+     * Have this player pass priority.
+     * @return whether priority was successfully passed.
+     */
     public abstract boolean passPriority();
+
+    /**
+     * Have this player silently pass priority until the end of the current
+     * turn, unless an event occurs.
+     * 
+     * @return whether priority was successfully passed.
+     */
     public abstract boolean passPriorityUntilEndOfTurn();
+
+    /**
+     * If possible, have this player use one mana of the specified kind.
+     * 
+     * @param mana
+     *            the mana to spend.
+     * @see MagicColor
+     */
     public abstract void useMana(byte mana);
+
+    /**
+     * If possible, have this player select a player.
+     * 
+     * @param player
+     *            the player to select.
+     * @param triggerEvent
+     *            the event used to select the player.
+     */
     public abstract void selectPlayer(PlayerView player, ITriggerEvent triggerEvent);
+
+    /**
+     * If possible, have this player select a card.
+     * 
+     * @param card
+     *            the card to select.
+     * @param triggerEvent
+     *            the event used to select the card.
+     */
     public abstract boolean selectCard(CardView card, ITriggerEvent triggerEvent);
+
+    /**
+     * If possible, have this player select a spellability.
+     * 
+     * @param sa
+     *            the spellability to select.
+     * @param triggerEvent
+     *            the event used to select the spellability.
+     */
     public abstract void selectAbility(SpellAbilityView sa);
+
+    /**
+     * If possible, have this player attack with as many creatures that can do
+     * so.
+     */
     public abstract void alphaStrike();
 
-    // the following method should eventually be replaced by methods returning
+    /**
-    // View classes
+     * Ask for a list containing the players involved in this game.
-    @Deprecated
+     * 
-    public abstract RegisteredPlayer getGuiRegisteredPlayer(LobbyPlayer p);
+     * @return a list of players.
-
+     */
     public abstract List<PlayerView> getPlayers();
 
+    /**
+     * Get the player whose turn it currently is.
+     * 
+     * @return the player whose turn it is, or {@code null} if it is no-one's
+     *         turn (eg. because the current player has lost the game this
+     *         turn).
+     */
     public abstract PlayerView getPlayerTurn();
 
+    /**
+     * @return the current phase the game is in.
+     */
     public abstract PhaseType getPhase();
 
+    /**
+     * @return a list of items currently on the stack.
+     */
     public abstract List<StackItemView> getStack();
+
+    /**
+     * @return the top item on the stack, or {@code null} if the stack is empty.
+     */
     public abstract StackItemView peekStack();
 
+    /**
+     * @param c
+     *            a card.
+     * @return whether this player may view the specified card.
+     */
     public abstract boolean mayShowCard(CardView c);
+
+    /**
+     * @param c
+     *            a card.
+     * @return whether this player may view the front card face of the specified
+     *         card.
+     */
     public abstract boolean mayShowCardFace(CardView c);
 
     // Auto-yield related methods
@@ -97,6 +246,10 @@ public interface IGameView {
     public abstract void setShouldAlwaysDeclineTrigger(Integer trigger);
     public abstract void setShouldAlwaysAskTrigger(Integer trigger);
 
+    /**
+     * Request cancellation of a previous request to pass priority
+     * automatically.
+     */
     public abstract void autoPassCancel();
 
     public abstract void devTogglePlayManyLands(boolean b);

forge-gui/src/main/java/forge/view/LocalGameView.java

@@ -200,19 +200,6 @@ public abstract class LocalGameView implements IGameView {
         return game.getGameLog().getLogEntriesExact(logLevel);
     }
 
-    /* (non-Javadoc)
-     * @see forge.view.IGameView#getGuiRegisteredPlayer(forge.LobbyPlayer)
-     */
-    @Override
-    public RegisteredPlayer getGuiRegisteredPlayer(final LobbyPlayer p) {
-        for (final RegisteredPlayer player : game.getMatch().getPlayers()) {
-            if (player.getPlayer() == p) {
-                return player;
-            }
-        }
-        return null;
-    }
-
     /* (non-Javadoc)
      * @see forge.view.IGameView#getRegisteredPlayers()
      */

forge-gui/src/main/java/forge/view/PlayerView.java

@@ -13,6 +13,14 @@ import forge.LobbyPlayer;
 import forge.card.MagicColor;
 import forge.game.zone.ZoneType;
 
+/**
+ * Representation of a {@link forge.game.player.Player}, containing only the
+ * information relevant to a user interface.
+ * 
+ * Conversion from and to Players happens through {@link LocalGameView}.
+ * 
+ * @author elcnesh
+ */
 public class PlayerView extends GameEntityView {
 
     private final LobbyPlayer lobbyPlayer;

forge-gui/src/main/java/forge/view/SpellAbilityView.java

@@ -1,5 +1,13 @@
 package forge.view;
 
+/**
+ * Representation of a {@link forge.game.spellability.SpellAbility}, containing
+ * only the information relevant to a user interface.
+ * 
+ * Conversion from and to SpellAbilities happens through {@link LocalGameView}.
+ * 
+ * @author elcnesh
+ */
 public class SpellAbilityView {
 
     private CardView hostCard;

forge-gui/src/main/java/forge/view/StackItemView.java

@@ -1,5 +1,14 @@
 package forge.view;
 
+/**
+ * Representation of a {@link forge.game.spellability.SpellAbilityStackInstance}
+ * , containing only the information relevant to a user interface.
+ * 
+ * Conversion from and to SpellAbilityStackInstances happens through
+ * {@link LocalGameView}.
+ * 
+ * @author elcnesh
+ */
 public class StackItemView {
 
     private final String key;

forge-gui/src/main/java/forge/view/ViewUtil.java

@@ -14,6 +14,11 @@ import forge.game.card.CardCharacteristics;
 import forge.item.IPaperCard;
 import forge.view.CardView.CardStateView;
 
+/**
+ * Static class providing utility methods to the view classes.
+ * 
+ * @author elcnesh
+ */
 public final class ViewUtil {
 
     private ViewUtil() {