diff --git a/src/main/java/net/rptools/maptool/client/functions/TokenLightFunctions.java b/src/main/java/net/rptools/maptool/client/functions/TokenLightFunctions.java
index 497731187f..b72271a03a 100644
--- a/src/main/java/net/rptools/maptool/client/functions/TokenLightFunctions.java
+++ b/src/main/java/net/rptools/maptool/client/functions/TokenLightFunctions.java
@@ -60,7 +60,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
 
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 0, 1);
       MapTool.serverCommand().updateTokenProperty(token, "clearLightSources");
-      MapTool.getFrame().updateTokenTree();
       return "";
     }
     if (functionName.equalsIgnoreCase("setLight")) {
@@ -158,9 +157,6 @@ private static BigDecimal setLight(Token token, String category, String name, Bi
       throw new ParserException(
           I18N.getText("macro.function.tokenLight.unknownLightType", "setLights", category));
     }
-    MapTool.getFrame().updateTokenTree();
-    token.getZoneRenderer().flushLight();
-
     return found ? BigDecimal.ONE : BigDecimal.ZERO;
   }
 
diff --git a/src/main/java/net/rptools/maptool/client/functions/TokenLocationFunctions.java b/src/main/java/net/rptools/maptool/client/functions/TokenLocationFunctions.java
index e7bdb4849b..668040af89 100644
--- a/src/main/java/net/rptools/maptool/client/functions/TokenLocationFunctions.java
+++ b/src/main/java/net/rptools/maptool/client/functions/TokenLocationFunctions.java
@@ -106,10 +106,8 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
                 1,
                 parameters.get(0).toString()));
       }
-      MapTool.serverCommand()
-          .updateTokenProperty(token, "setZOrder", ((BigDecimal) parameters.get(0)).intValue());
-      ZoneRenderer renderer = MapTool.getFrame().getCurrentZoneRenderer();
-      renderer.flushLight();
+      int newZOrder = ((BigDecimal) parameters.get(0)).intValue();
+      MapTool.serverCommand().updateTokenProperty(token, "setZOrder", newZOrder);
       return BigDecimal.valueOf(token.getZOrder());
     }
     if (functionName.equals("getDistance")) {
@@ -595,7 +593,6 @@ private static String moveToken(MapToolVariableResolver res, List<Object> args)
 
     ZonePoint zp = getZonePoint(x, y, useDistance);
     MapTool.serverCommand().updateTokenProperty(token, "setXY", zp.x, zp.y);
-    token.getZoneRenderer().flushLight();
     return "";
   }
 
diff --git a/src/main/java/net/rptools/maptool/client/functions/TokenPropertyFunctions.java b/src/main/java/net/rptools/maptool/client/functions/TokenPropertyFunctions.java
index 3a553d5197..e5a7dd3870 100644
--- a/src/main/java/net/rptools/maptool/client/functions/TokenPropertyFunctions.java
+++ b/src/main/java/net/rptools/maptool/client/functions/TokenPropertyFunctions.java
@@ -202,8 +202,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
       FunctionUtil.checkNumberParam(functionName, parameters, 0, 2);
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 0, 1);
       MapTool.serverCommand().updateTokenProperty(token, functionName);
-      token.getZoneRenderer().flushLight();
-      MapTool.getFrame().updateTokenTree();
       return "";
     }
 
@@ -214,8 +212,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
       FunctionUtil.checkNumberParam(functionName, parameters, 0, 2);
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 0, 1);
       MapTool.serverCommand().updateTokenProperty(token, functionName);
-      token.getZoneRenderer().flushLight();
-      MapTool.getFrame().updateTokenTree();
       return "";
     }
 
@@ -239,8 +235,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
       }
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 1, 3);
       String layer = setLayer(token, parameters.get(0).toString(), forceShape);
-      token.getZoneRenderer().flushLight();
-      MapTool.getFrame().updateTokenTree();
       return layer;
     }
 
@@ -605,10 +599,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
       BigDecimal facing = getBigDecimalFromParam(functionName, parameters, 0);
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 1, 2);
       MapTool.serverCommand().updateTokenProperty(token, "setFacing", facing.intValue());
-      token
-          .getZoneRenderer()
-          .flushLight(); // FJE This isn't needed unless the token had a light source, right? Should
-      // we check for that?
       return "";
     }
 
@@ -619,7 +609,6 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
       FunctionUtil.checkNumberParam(functionName, parameters, 0, 2);
       Token token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 0, 1);
       MapTool.serverCommand().updateTokenProperty(token, "setFacing", (Integer) null);
-      token.getZoneRenderer().flushLight();
       return "";
     }
 
@@ -776,10 +765,9 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
 
       double magnitude = getBigDecimalFromParam(functionName, parameters, 0).doubleValue();
       Rectangle tokenBounds = token.getBounds(zone);
+
       double oldWidth = tokenBounds.width;
       double oldHeight = tokenBounds.height;
-      MapTool.serverCommand().updateTokenProperty(token, "setSnapToScale", false);
-
       double newScaleX;
       double newScaleY;
       if (functionName.equals("setTokenWidth")) {
@@ -839,16 +827,10 @@ private String setSize(Token token, String size) throws ParserException {
       MapTool.serverCommand().updateTokenProperty(token, "setSnapToScale", false);
       return getSize(token);
     }
-    MapTool.serverCommand().updateTokenProperty(token, "setSnapToScale", true);
-    ZoneRenderer renderer = token.getZoneRenderer();
-    Zone zone = renderer.getZone();
-    Grid grid = zone.getGrid();
+    Grid grid = token.getZoneRenderer().getZone().getGrid();
     for (TokenFootprint footprint : grid.getFootprints()) {
       if (footprint.getName().equalsIgnoreCase(size)) {
         MapTool.serverCommand().updateTokenProperty(token, "setFootprint", grid, footprint);
-        renderer.flush(token);
-        renderer.repaint();
-        MapTool.getFrame().updateTokenTree();
         return getSize(token);
       }
     }
@@ -862,12 +844,9 @@ private String setSize(Token token, String size) throws ParserException {
    * @param token The token to reset the size of.
    */
   private void resetSize(Token token) {
-    MapTool.serverCommand().updateTokenProperty(token, "setSnapToScale", true);
-    ZoneRenderer renderer = token.getZoneRenderer();
-    Zone zone = renderer.getZone();
-    Grid grid = zone.getGrid();
-    MapTool.serverCommand()
-        .updateTokenProperty(token, "setFootprint", grid, grid.getDefaultFootprint());
+    Grid grid = token.getZoneRenderer().getZone().getGrid();
+    TokenFootprint footprint = grid.getDefaultFootprint();
+    MapTool.serverCommand().updateTokenProperty(token, "setFootprint", grid, footprint);
   }
 
   /**
@@ -896,8 +875,8 @@ public static Zone.Layer getLayer(String layerName) throws ParserException {
   }
 
   /**
-   * Get the token shape corresponding to the token & layer. Returns null if can't find match, or if
-   * forceShape is set to false.
+   * Get the token shape corresponding to the token and layer. Returns null if can't find match, or
+   * if forceShape is set to false.
    *
    * @param token the token to get the new shape of.
    * @param layer the layer of the token.
diff --git a/src/main/java/net/rptools/maptool/client/functions/TokenSightFunctions.java b/src/main/java/net/rptools/maptool/client/functions/TokenSightFunctions.java
index 4af83a8b02..cc787ca31f 100644
--- a/src/main/java/net/rptools/maptool/client/functions/TokenSightFunctions.java
+++ b/src/main/java/net/rptools/maptool/client/functions/TokenSightFunctions.java
@@ -72,16 +72,14 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
     token = FunctionUtil.getTokenFromParam(resolver, functionName, parameters, 1, 2);
 
     if (functionName.equals("setHasSight")) {
-      MapTool.serverCommand()
-          .updateTokenProperty(token, "setHasSight", !parameters.get(0).equals(BigDecimal.ZERO));
-      token.getZoneRenderer().flushLight();
+      boolean hasSight = !parameters.get(0).equals(BigDecimal.ZERO);
+      MapTool.serverCommand().updateTokenProperty(token, "setHasSight", hasSight);
       return token.getHasSight() ? BigDecimal.ONE : BigDecimal.ZERO;
     }
 
     if (functionName.equals("setSightType")) {
-      MapTool.serverCommand()
-          .updateTokenProperty(token, "setSightType", parameters.get(0).toString());
-      token.getZoneRenderer().flushLight();
+      String sightType = parameters.get(0).toString();
+      MapTool.serverCommand().updateTokenProperty(token, "setSightType", sightType);
       return token.getSightType();
     }
 
diff --git a/src/main/java/net/rptools/maptool/client/functions/VBL_Functions.java b/src/main/java/net/rptools/maptool/client/functions/VBL_Functions.java
index 27efd075b0..f5e2d2c842 100644
--- a/src/main/java/net/rptools/maptool/client/functions/VBL_Functions.java
+++ b/src/main/java/net/rptools/maptool/client/functions/VBL_Functions.java
@@ -275,14 +275,8 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
             break;
         }
       }
-
       // Replace with new VBL
       MapTool.serverCommand().updateTokenProperty(token, "setVBL", tokenVBL);
-
-      // Force a TOPOLOGY_CHANGED event. This made the client performing the
-      // VBL change actually show the change but not the other clients.
-      renderer.getZone().tokenTopologyChanged();
-      renderer.repaint();
     }
 
     if (functionName.equals("transferVBL")) {
@@ -363,19 +357,18 @@ public Object childEvaluate(Parser parser, String functionName, List<Object> par
   /**
    * Get the required parameters needed from the JSON to draw a rectangle and render as VBL.
    *
-   * @param renderer Reference to the ZoneRenderer
+   * @param renderer Reference to the ZoneRenderer. Can be null.
    * @param vblObject The JSONObject containing all the coordinates and values to needed to draw a
    *     rectangle.
-   * @param erase Set to true to erase the rectangle in VBL, otherwise draw it
-   * @return
-   * @throws ParserException If the minimum required parameters are not present in the JSON, throw
-   *     ParserException
+   * @param erase Set to true to erase the rectangle in VBL, otherwise draw it.
+   * @return the VBL area if the renderer is null, and null otherwise.
+   * @throws ParserException If the minimum required parameters are not present in the JSON.
    */
   private Area drawRectangleVBL(ZoneRenderer renderer, JSONObject vblObject, boolean erase)
       throws ParserException {
     String funcname = "drawVBL[Rectangle]";
     // Required Parameters
-    String requiredParms[] = {"x", "y", "w", "h"};
+    String[] requiredParms = {"x", "y", "w", "h"};
     if (!jsonKeysExist(vblObject, requiredParms, funcname))
       throw new ParserException(
           I18N.getText("macro.function.general.argumentKeyTypeI", funcname, "{x,y,w,h}"));
@@ -491,9 +484,8 @@ private void applyScale(
    * @param vblObject The JSONObject containing all the coordinates and values to needed to draw a
    *     rectangle.
    * @param erase Set to true to erase the rectangle in VBL, otherwise draw it
-   * @return
-   * @throws ParserException If the minimum required parameters are not present in the JSON, throw
-   *     ParserException
+   * @return the VBL area if the renderer is null, and null otherwise.
+   * @throws ParserException If the minimum required parameters are not present in the JSON.
    */
   private Area drawPolygonVBL(ZoneRenderer renderer, JSONObject vblObject, boolean erase)
       throws ParserException {
@@ -611,9 +603,8 @@ private Area drawPolygonVBL(ZoneRenderer renderer, JSONObject vblObject, boolean
    * @param vblObject The JSONObject containing all the coordinates and values to needed to draw a
    *     rectangle.
    * @param erase Set to true to erase the rectangle in VBL, otherwise draw it
-   * @return the token.
-   * @throws ParserException If the minimum required parameters are not present in the JSON, throw
-   *     ParserException
+   * @return the VBL area if the renderer is null, and null otherwise.
+   * @throws ParserException If the minimum required parameters are not present in the JSON.
    */
   private Area drawCrossVBL(ZoneRenderer renderer, JSONObject vblObject, boolean erase)
       throws ParserException {
@@ -694,9 +685,8 @@ private Area drawCrossVBL(ZoneRenderer renderer, JSONObject vblObject, boolean e
    * @param vblObject The JSONObject containing all the coordinates and values to needed to draw a
    *     rectangle.
    * @param erase Set to true to erase the rectangle in VBL, otherwise draw it
-   * @return
-   * @throws ParserException If the minimum required parameters are not present in the JSON, throw
-   *     ParserException
+   * @return the VBL area if the renderer is null, and null otherwise.
+   * @throws ParserException If the minimum required parameters are not present in the JSON.
    */
   private Area drawCircleVBL(ZoneRenderer renderer, JSONObject vblObject, boolean erase)
       throws ParserException {
@@ -781,10 +771,10 @@ private Area drawCircleVBL(ZoneRenderer renderer, JSONObject vblObject, boolean
    * Get the required parameters needed from the JSON to get/set VBL within a defined rectangle.
    *
    * @param renderer Reference to the ZoneRenderer
-   * @param vblObject The JSONObject containing all the coordinates and values to needed to draw a
+   * @param vblObject JSONObject containing all the coordinates and values needed to draw a
    *     rectangle.
-   * @throws ParserException If the minimum required parameters are not present in the JSON, throw
-   *     ParserException
+   * @return the VBL area.
+   * @throws ParserException If the minimum required parameters are not present in the JSON.
    */
   private Area getVBL(ZoneRenderer renderer, JSONObject vblObject) throws ParserException {
     String funcname = "getVBL[Rectangle]";
diff --git a/src/main/java/net/rptools/maptool/client/tool/PointerTool.java b/src/main/java/net/rptools/maptool/client/tool/PointerTool.java
index 0cd639fdcd..5b96f2a918 100644
--- a/src/main/java/net/rptools/maptool/client/tool/PointerTool.java
+++ b/src/main/java/net/rptools/maptool/client/tool/PointerTool.java
@@ -254,6 +254,11 @@ public void stopTokenDrag() {
     exposeFoW(null);
   }
 
+  /**
+   * Expose the FoW at a ZonePoint, or at the visible area, for the selected token
+   *
+   * @param p the ZonePoint to expose, or a null if exposing visible area and last path
+   */
   public void exposeFoW(ZonePoint p) {
     // if has fog(required)
     // and ((isGM with pref set) OR serverPolicy allows auto reveal by players)
diff --git a/src/main/java/net/rptools/maptool/client/ui/MapToolFrame.java b/src/main/java/net/rptools/maptool/client/ui/MapToolFrame.java
index 484c4c0df3..056f944323 100644
--- a/src/main/java/net/rptools/maptool/client/ui/MapToolFrame.java
+++ b/src/main/java/net/rptools/maptool/client/ui/MapToolFrame.java
@@ -178,7 +178,9 @@ public class MapToolFrame extends DefaultDockableHolder
   // Components
   private final AssetPanel assetPanel;
   private final ClientConnectionPanel connectionPanel;
+  /** The panel showing the initiative order. */
   private final InitiativePanel initiativePanel;
+
   private final PointerOverlay pointerOverlay;
   private final CommandPanel commandPanel;
   private final AboutDialog aboutDialog;
@@ -212,7 +214,9 @@ public class MapToolFrame extends DefaultDockableHolder
   private final ChatTyperObserver chatTyperObserver;
 
   private final GlassPane glassPane;
+  /** Model for the token tree panel of the map explorer. */
   private TokenPanelTreeModel tokenPanelTreeModel;
+
   private DrawPanelTreeModel drawPanelTreeModel;
   private DrawablesPanel drawablesPanel;
   private final TextureChooserPanel textureChooserPanel;
@@ -225,7 +229,7 @@ public class MapToolFrame extends DefaultDockableHolder
   private JFileChooser savePropsFileChooser;
   private JFileChooser saveFileChooser;
 
-  // Remember the last layer selected
+  /** Remember the last layer selected */
   private Layer lastSelectedLayer = Zone.Layer.TOKEN;
 
   private final FileFilter campaignFilter =
@@ -788,6 +792,7 @@ public EditTokenDialog getTokenPropertiesDialog() {
     return tokenPropertiesDialog;
   }
 
+  /** Repaints the current ZoneRenderer, if it is not null. */
   public void refresh() {
     if (getCurrentZoneRenderer() != null) {
       getCurrentZoneRenderer().repaint();
@@ -1214,6 +1219,7 @@ public void updateDrawTree() {
     }
   }
 
+  /** Create the token tree panel for the map explorer */
   private JComponent createTokenTreePanel() {
     final JTree tree = new JTree();
     tokenPanelTreeModel = new TokenPanelTreeModel(tree);
@@ -1311,6 +1317,7 @@ public void clearTokenTree() {
     }
   }
 
+  /** Update tokenPanelTreeModel and the initiativePanel. */
   public void updateTokenTree() {
     if (tokenPanelTreeModel != null) {
       tokenPanelTreeModel.update();
diff --git a/src/main/java/net/rptools/maptool/client/ui/tokenpanel/InitiativePanel.java b/src/main/java/net/rptools/maptool/client/ui/tokenpanel/InitiativePanel.java
index 1f97146cec..e4a864a77e 100644
--- a/src/main/java/net/rptools/maptool/client/ui/tokenpanel/InitiativePanel.java
+++ b/src/main/java/net/rptools/maptool/client/ui/tokenpanel/InitiativePanel.java
@@ -298,7 +298,7 @@ public void clearTokens() {
     list.clearModel();
   }
 
-  /** Make sure that the token references match the zone */
+  /** Update list containing tokens in initiative. Make sure the token references match the zone. */
   public void update() {
     list.update();
   }
diff --git a/src/main/java/net/rptools/maptool/client/ui/tokenpanel/TokenPanelTreeModel.java b/src/main/java/net/rptools/maptool/client/ui/tokenpanel/TokenPanelTreeModel.java
index 559eaac07b..a37cc90938 100644
--- a/src/main/java/net/rptools/maptool/client/ui/tokenpanel/TokenPanelTreeModel.java
+++ b/src/main/java/net/rptools/maptool/client/ui/tokenpanel/TokenPanelTreeModel.java
@@ -72,7 +72,7 @@ public enum View {
     Zone.Layer layer;
     boolean isAdmin;
 
-    private View(String key, Zone.Layer layer, boolean required, boolean isAdmin) {
+    View(String key, Zone.Layer layer, boolean required, boolean isAdmin) {
       this.displayName = I18N.getText(key);
       this.description = null; // I18N.getDescription(key); // TODO Tooltip -- not currently used
       this.required = required;
@@ -97,10 +97,13 @@ public boolean isRequired() {
     }
   }
 
+  /** The list of token filters. */
   private final List<TokenFilter> filterList = new ArrayList<TokenFilter>();
+
   private final String root = "Views";
   private Zone zone;
   private final JTree tree;
+  /** Is an updateInternal pending? */
   private volatile boolean updatePending = false;
 
   public TokenPanelTreeModel(JTree tree) {
@@ -126,6 +129,11 @@ public Object getRoot() {
     return root;
   }
 
+  /**
+   * Set the zone, updating the listeners and the internals.
+   *
+   * @param zone the Zone to set.
+   */
   public void setZone(Zone zone) {
     if (zone != null) {
       zone.removeModelChangeListener(this);
@@ -192,6 +200,10 @@ public void removeTreeModelListener(TreeModelListener l) {
     listenerList.remove(l);
   }
 
+  /**
+   * Run updateInternal on the EventQueue. This clears currentViewList and viewMap, and adds views
+   * in the filterList to currentViewList.
+   */
   public void update() {
     // better solution would be to use a timeout to invoke the internal update to give more
     // token events the chance to arrive, but in this case EventQueue overload will
@@ -208,6 +220,7 @@ public void run() {
     }
   }
 
+  /** Clear currentViewList and viewMap, and add views in the filterList to currentViewList */
   private void updateInternal() {
     currentViewList.clear();
     viewMap.clear();
@@ -308,6 +321,7 @@ private void filter(Token token) {
    * useStrictTokenManagement() into account).
    */
   private class PlayerTokenFilter extends TokenFilter {
+    /** Accepts only PCs tokens owned by the current player. */
     public PlayerTokenFilter() {
       super(View.PLAYERS);
     }
@@ -392,6 +406,7 @@ protected boolean accept(Token token) {
    * </ol>
    */
   private class TokenTokenFilter extends TokenFilter {
+    /** Accepts only NPC tokens (GM) or tokens owned by current player. */
     public TokenTokenFilter() {
       super(View.TOKENS);
     }
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/FogUtil.java b/src/main/java/net/rptools/maptool/client/ui/zone/FogUtil.java
index 4e4dbfe322..7e7ae6183e 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/FogUtil.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/FogUtil.java
@@ -61,6 +61,15 @@
 public class FogUtil {
   private static final Logger log = LogManager.getLogger(FogUtil.class);
 
+  /**
+   * Return the visible area for an origin, a lightSourceArea and a VBL.
+   *
+   * @param x the x vision origin.
+   * @param y the y vision origin.
+   * @param vision the lightSourceArea.
+   * @param topology the VBL topology.
+   * @return the visible area.
+   */
   public static Area calculateVisibility(int x, int y, Area vision, AreaTree topology) {
     CodeTimer timer = new CodeTimer("calculateVisibility");
 
@@ -128,6 +137,13 @@ public static Area calculateVisibility(int x, int y, Area vision, AreaTree topol
     return vision;
   }
 
+  /**
+   * Expose visible area and previous path of all tokens in the token set. Server and clients are
+   * updated.
+   *
+   * @param renderer the ZoneRenderer of the map
+   * @param tokenSet the set of GUID of the tokens
+   */
   public static void exposeVisibleArea(final ZoneRenderer renderer, Set<GUID> tokenSet) {
     exposeVisibleArea(renderer, tokenSet, false);
   }
@@ -289,7 +305,7 @@ private static void clearExposedArea(Zone zone, boolean globalOnly) {
    *
    * @author Jamz
    * @since 1.4.0.1
-   * @param renderer
+   * @param renderer the ZoneRenderer
    */
   public static void exposeAllOwnedArea(ZoneRenderer renderer) {
     Set<GUID> tokenSet = new HashSet<GUID>();
@@ -319,7 +335,7 @@ public static void exposeAllOwnedArea(ZoneRenderer renderer) {
   /**
    * Restore the FoW on one map. Updates server and clients.
    *
-   * @param renderer the ZoneRenderer of the map
+   * @param renderer the ZoneRenderer of the map.
    */
   public static void restoreFoW(final ZoneRenderer renderer) {
     // System.out.println("Zone ID: " + renderer.getZone().getId());
@@ -414,7 +430,10 @@ public static void exposeLastPath(final ZoneRenderer renderer, final Set<GUID> t
   /**
    * Find the center point of a vision TODO: This is a horrible horrible method. the API is just
    * plain disgusting. But it'll work to consolidate all the places this has to be done until we can
-   * encapsulate it into the vision itself
+   * encapsulate it into the vision itself.
+   *
+   * @param token the token to get the vision center of.
+   * @param zone the Zone where the token is.
    */
   public static Point calculateVisionCenter(Token token, Zone zone) {
     Grid grid = zone.getGrid();
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/PlayerView.java b/src/main/java/net/rptools/maptool/client/ui/zone/PlayerView.java
index d9e82db93a..a2ea999d71 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/PlayerView.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/PlayerView.java
@@ -19,8 +19,10 @@
 import net.rptools.maptool.model.Token;
 
 public class PlayerView {
+  /** The role of the player (GM or PLAYER). */
   private final Player.Role role;
-  private final List<Token> tokens; // Optional
+  /** Restrict the view to these tokens. Optional. */
+  private final List<Token> tokens;
 
   // Optimization
   private final String hash;
@@ -47,6 +49,7 @@ public List<Token> getTokens() {
     return tokens;
   }
 
+  /** @return true if the view is for some tokens only, false if the view is global */
   public boolean isUsingTokenView() {
     return tokens != null;
   }
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRenderer.java b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRenderer.java
index 242b56d65c..67259ffc75 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRenderer.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRenderer.java
@@ -199,10 +199,15 @@ public class ZoneRenderer extends JComponent
   private String loadingProgress;
   private boolean isLoaded;
   private BufferedImage fogBuffer;
-  // I don't like this, at all, but it'll work for now, basically keep track of when the fog cache
-  // needs to be flushed in the case of switching views
+  /**
+   * I don't like this, at all, but it'll work for now, basically keep track of when the fog cache
+   * needs to be flushed in the case of switching views
+   */
   private boolean flushFog = true;
-  private Area exposedFogArea; // In screen space
+
+  /** In screen space */
+  private Area exposedFogArea;
+
   private BufferedImage miniImage;
   private BufferedImage backbuffer;
   private boolean drawBackground = true;
@@ -217,19 +222,25 @@ public class ZoneRenderer extends JComponent
 
   private boolean autoResizeStamp = false;
 
-  // Show blocked grid lines during AStar moving, for debugging...
+  /** Show blocked grid lines during AStar moving, for debugging... */
   private boolean showAstarDebugging = false;
 
-  // Store previous view to restore to, eg after GM shows ctrl+shift+space pointer
+  /** Store previous view to restore to, eg after GM shows ctrl+shift+space pointer */
   private double previousScale;
+
   private ZonePoint previousZonePoint;
 
-  public static enum TokenMoveCompletion {
+  public enum TokenMoveCompletion {
     TRUE,
     FALSE,
     OTHER
   }
 
+  /**
+   * Constructor for the ZoneRenderer from a zone.
+   *
+   * @param zone the zone of the ZoneRenderer
+   */
   public ZoneRenderer(Zone zone) {
     if (zone == null) {
       throw new IllegalArgumentException("Zone cannot be null");
@@ -613,7 +624,11 @@ public void commitMoveSelectionSet(GUID keyTokenId) {
     if (vblTokenMoved) zone.tokenTopologyChanged();
   }
 
-  /** @param token */
+  /**
+   * Undo the last movement.
+   *
+   * @param token the token for which we undo the movement
+   */
   private void denyMovement(final Token token) {
     Path<?> path = token.getLastPath();
     if (path != null) {
@@ -668,6 +683,13 @@ public void centerOn(CellPoint point) {
     centerOn(zone.getGrid().convert(point));
   }
 
+  /**
+   * Remove the token from: tokenLocationCache, flipImageMap, opacityImageMap, replacementImageMap,
+   * labelRenderingCache. Set the visibleScreenArea, tokenStackMap, renderedLightMap, rendered Aura
+   * map to null. Flush the fog. Flush the token from the zoneView.
+   *
+   * @param token the token to flush
+   */
   public void flush(Token token) {
     // This method can be called from a non-EDT thread so if that happens, make sure
     // we synchronize with the EDT.
@@ -693,6 +715,7 @@ public void flush(Token token) {
     zoneView.flush(token);
   }
 
+  /** @return the ZoneView */
   public ZoneView getZoneView() {
     return zoneView;
   }
@@ -720,6 +743,7 @@ public void flush() {
     isLoaded = false;
   }
 
+  /** Set the rendererLightMap and renderedAuraMap to null, flush the zoneView, and repaint. */
   public void flushLight() {
     renderedLightMap = null;
     renderedAuraMap = null;
@@ -727,12 +751,14 @@ public void flushLight() {
     repaintDebouncer.dispatch();
   }
 
+  /** Set flushFog to true, visibleScreenArea to null, and repaints */
   public void flushFog() {
     flushFog = true;
     visibleScreenArea = null;
     repaintDebouncer.dispatch();
   }
 
+  /** @return the Zone */
   public Zone getZone() {
     return zone;
   }
@@ -869,8 +895,8 @@ public PlayerView getPlayerView() {
    * The returned {@link PlayerView} contains a list of tokens that includes all selected tokens
    * that this player owns and that have their <code>HasSight</code> checkbox enabled.
    *
-   * @param role
-   * @return
+   * @param role the player role
+   * @return the player view
    */
   public PlayerView getPlayerView(Player.Role role) {
     List<Token> selectedTokens = null;
@@ -904,6 +930,7 @@ public Rectangle fogExtents() {
    * created by copying renderZone() and then replacing each bit of rendering with a routine to
    * simply aggregate the extents of the object that would have been rendered.
    *
+   * @param view the player view
    * @return a new Rectangle with the bounding box of all the elements in the Zone
    */
   public Rectangle zoneExtents(PlayerView view) {
@@ -1390,8 +1417,16 @@ public CodeTimer getCodeTimer() {
     return timer;
   }
 
+  /** Map of the lights from drawableLightCache that have been combined. */
   private Map<Paint, List<Area>> renderedLightMap;
 
+  /**
+   * Render the lights. Get the lights from drawableLightCache, combine them, put them in
+   * renderedLightMap, and draw them.
+   *
+   * @param g the graphic 2D object
+   * @param view the player view
+   */
   private void renderLights(Graphics2D g, PlayerView view) {
     // Setup
     timer.start("lights-1");
@@ -1435,7 +1470,7 @@ private void renderLights(Graphics2D g, PlayerView view) {
           // I'm not a huge fan of this hard wiring, but I haven't thought of a better way yet, so
           // this'll
           // work fine for now
-          otherLightList.add(light);
+          otherLightList.add(light); // not used for anything?!
         }
       }
       timer.stop("lights-3");
@@ -1493,8 +1528,16 @@ private void renderLights(Graphics2D g, PlayerView view) {
     newG.dispose();
   }
 
+  /** Holds the auras from lightSourceMap after they have been combined. */
   private Map<Paint, Area> renderedAuraMap;
 
+  /**
+   * Get the list of auras from lightSourceMap, combine them, store them in renderedAuraMap, and
+   * draw them.
+   *
+   * @param g the Graphics2D object.
+   * @param view the player view.
+   */
   private void renderAuras(Graphics2D g, PlayerView view) {
     // Setup
     timer.start("auras-1");
@@ -2743,7 +2786,7 @@ public void addDistanceText(Graphics2D g, ZonePoint point, float size, double di
    * Get a list of tokens currently visible on the screen. The list is ordered by location starting
    * in the top left and going to the bottom right.
    *
-   * @return
+   * @return the token list
    */
   public List<Token> getTokensOnScreen() {
     List<Token> list = new ArrayList<Token>();
@@ -3730,7 +3773,11 @@ public void selectTokens(Collection<GUID> tokens) {
     HTMLFrameFactory.selectedListChanged();
   }
 
-  /** Screen space rectangle */
+  /**
+   * Screen space rectangle
+   *
+   * @param rect the selection rectangle
+   */
   public void selectTokens(Rectangle rect) {
     List<GUID> selectedList = new LinkedList<GUID>();
     for (TokenLocation location : getTokenLocations(getActiveLayer())) {
@@ -3883,9 +3930,9 @@ public Rectangle getLabelBounds(Label label) {
    *
    * <p>TODO: Add a check so that tokens owned by the current player are given priority.
    *
-   * @param x
-   * @param y
-   * @return
+   * @param x screen location x
+   * @param y screen location y
+   * @return the token
    */
   public Token getTokenAt(int x, int y) {
     List<TokenLocation> locationList = new ArrayList<TokenLocation>();
@@ -3925,9 +3972,9 @@ public List<Token> getTokenStackAt(int x, int y) {
    * Returns the label at screen location x, y (not cell location). To get the token at a cell
    * location, use getGameMap() and use that.
    *
-   * @param x
-   * @param y
-   * @return
+   * @param x the screen location x
+   * @param y the screen location y
+   * @return the Label
    */
   public Label getLabelAt(int x, int y) {
     List<LabelLocation> labelList = new ArrayList<LabelLocation>();
@@ -4103,8 +4150,9 @@ public class SelectionSet {
     private ZoneWalker walker;
     private final Token token;
     private Path<ZonePoint> gridlessPath;
-    // Pixel distance from keyToken's origin
+    /** Pixel distance (x) from keyToken's origin. */
     private int offsetX;
+    /** Pixel distance (y) from keyToken's origin. */
     private int offsetY;
     // private boolean restrictMovement = true;
     private RenderPathWorker renderPathTask;
@@ -4131,7 +4179,7 @@ public SelectionSet(String playerId, GUID tokenGUID, Set<GUID> selectionList) {
       }
     }
 
-    // Lee: adding getter for path computation
+    /** @return path computation. */
     public Path<ZonePoint> getGridlessPath() {
       return gridlessPath;
     }
@@ -4217,6 +4265,8 @@ public void toggleWaypoint(ZonePoint location) {
     /**
      * Retrieves the last waypoint, or if there isn't one then the start point of the first path
      * segment.
+     *
+     * @return the ZonePoint.
      */
     public ZonePoint getLastWaypoint() {
       ZonePoint zp;
@@ -4520,7 +4570,7 @@ private void addTokens(
    * Checks to see if token has an image table and references that if the token has a facing
    * otherwise uses basic image
    *
-   * @param token
+   * @param token the token to get the image from.
    * @return BufferedImage
    */
   private BufferedImage getTokenImage(Token token) {
@@ -4582,9 +4632,14 @@ public List<Token> getVisibleTokens() {
    */
   public void dropActionChanged(DropTargetDragEvent dtde) {}
 
-  //
-  // ZONE MODEL CHANGE LISTENER
+  /** ZONE MODEL CHANGE LISTENER */
   private class ZoneModelChangeListener implements ModelChangeListener {
+    /**
+     * ALL events trigger updateTokenTree and a repaint. Reacts specifically to events
+     * TOPOLOGY_CHANGED, TOKEN_CHANGED, TOKEN_REMOVED, and TOKEN_ADDED.
+     *
+     * @param event the event
+     */
     public void modelChanged(ModelChangeEvent event) {
       Object evt = event.getEvent();
 
@@ -4608,7 +4663,7 @@ public void modelChanged(ModelChangeEvent event) {
       if (evt == Zone.Event.FOG_CHANGED) {
         flushFog = true;
       }
-      MapTool.getFrame().updateTokenTree();
+      MapTool.getFrame().updateTokenTree(); // for any event
       repaintDebouncer.dispatch();
     }
   }
@@ -4655,6 +4710,9 @@ public void setHighlightCommonMacros(List<Token> affectedTokens) {
    * applied as the mouse pointer so there is no visual effect. Hence it's currently commented out
    * by using an "if (false)" around the code block.
    *
+   * <p>Merudo: applied correctly now? TODO: replace false by proper condition.
+   *
+   * @param cursor the cursor to set.
    * @see java.awt.Component#setCursor(java.awt.Cursor)
    */
   @SuppressWarnings("unused")
@@ -4669,6 +4727,13 @@ public void setCursor(Cursor cursor) {
 
   private Cursor custom = null;
 
+  /**
+   * Create a custom cursor.
+   *
+   * @param resource the String corresponding to the buffered image.
+   * @param tokenName the name of the token, to be displayed by the cursor.
+   * @return the created cursor.
+   */
   public Cursor createCustomCursor(String resource, String tokenName) {
     Cursor c = null;
     try {
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRendererFactory.java b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRendererFactory.java
index cbf17b3727..c12312c099 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRendererFactory.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneRendererFactory.java
@@ -18,6 +18,11 @@
 import net.rptools.maptool.model.Zone;
 
 public class ZoneRendererFactory {
+  /**
+   * Create a new ZoneRenderer from a zone.
+   *
+   * @param zone the Zone.
+   */
   public static ZoneRenderer newRenderer(Zone zone) {
     ZoneRenderer renderer = new ZoneRenderer(zone);
     if (MapTool.getFrame() != null) {
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneView.java b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneView.java
index 1fb07ea0d2..c569c47273 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/ZoneView.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/ZoneView.java
@@ -57,37 +57,58 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/** Responsible for calculating lights and vision. */
 public class ZoneView implements ModelChangeListener {
   private static final Logger log = LogManager.getLogger(ZoneView.class);
 
+  /** The zone of the ZoneView. */
   private final Zone zone;
 
   // VISION
+  /** Map each token to the area they can see by themselves. */
   private final Map<GUID, Area> tokenVisibleAreaCache = new HashMap<GUID, Area>();
+  /** Map each token to their current vision, depending on other lights. */
   private final Map<GUID, Area> tokenVisionCache = new HashMap<GUID, Area>();
+  /** Map lightSourceToken to the areaBySightMap. */
   private final Map<GUID, Map<String, TreeMap<Double, Area>>> lightSourceCache =
       new HashMap<GUID, Map<String, TreeMap<Double, Area>>>();
+  /** Map light source type to all tokens with that type. */
   private final Map<LightSource.Type, Set<GUID>> lightSourceMap =
       new HashMap<LightSource.Type, Set<GUID>>();
+  /** Map each token to their map between sightType and set of lights. */
   private final Map<GUID, Map<String, Set<DrawableLight>>> drawableLightCache =
       new HashMap<GUID, Map<String, Set<DrawableLight>>>();
+  /** Map each token to their map between sightType and set of bright lights. */
   private final Map<GUID, Map<String, Set<Area>>> brightLightCache =
       new Hashtable<GUID, Map<String, Set<Area>>>();
+  /** Map the PlayerView to its visible area. */
   private final Map<PlayerView, VisibleAreaMeta> visibleAreaMap =
       new HashMap<PlayerView, VisibleAreaMeta>();
-  private final SortedMap<Double, Area> allLightAreaMap =
-      new ConcurrentSkipListMap<Double, Area>(); // Hold all of our lights combined by lumens
+  /** Hold all of our lights combined by lumens. */
+  private final SortedMap<Double, Area> allLightAreaMap = new ConcurrentSkipListMap<Double, Area>();
 
-  // private AreaData topologyAreaData;
+  /** The digested topology of the map VBL, and possibly tokens VBL. */
   private AreaTree topologyTree;
-  private Area tokenTopolgy;
+  /** The VBL area of the zone VBL and the tokens VBL. */
+  private Area tokenTopology;
 
+  /**
+   * Construct ZoneView from zone. Build lightSourceMap, and add ZoneView to Zone as listener.
+   *
+   * @param zone the Zone to add.
+   */
   public ZoneView(Zone zone) {
     this.zone = zone;
     findLightSources();
     zone.addModelChangeListener(this);
   }
 
+  /**
+   * Calculate the visible area of the view, cache it in visibleAreaMap, and return it
+   *
+   * @param view the PlayerView
+   * @return the visible area
+   */
   public Area getVisibleArea(PlayerView view) {
     calculateVisibleArea(view);
     ZoneView.VisibleAreaMeta visible = visibleAreaMap.get(view);
@@ -98,30 +119,40 @@ public Area getVisibleArea(PlayerView view) {
     return visible != null ? visible.visibleArea : new Area();
   }
 
+  /**
+   * Get the vision status of the zone.
+   *
+   * @return true if the vision of the zone is not of type VisionType.OFF
+   */
   public boolean isUsingVision() {
     return zone.getVisionType() != Zone.VisionType.OFF;
   }
 
-  // Returns the current combined VBL (base VBL + TokenVBL)
+  /** @return the current combined VBL (base VBL + TokenVBL) */
   public synchronized AreaTree getTopologyTree() {
     return getTopologyTree(true);
   }
 
-  // topologyTree is "cached" and should only regenerate when topologyTree is null which should
-  // happen on flush calls
+  /**
+   * Get the topologyTree. The topologyTree is "cached" and should only regenerate when topologyTree
+   * is null which should happen on flush calls.
+   *
+   * @param useTokenVBL using token VBL? If so and topology null, create one from VBL tokens.
+   * @return the AreaTree (topologyTree).
+   */
   public synchronized AreaTree getTopologyTree(boolean useTokenVBL) {
-    if (tokenTopolgy == null && useTokenVBL) {
+    if (tokenTopology == null && useTokenVBL) {
       log.debug("ZoneView topologyTree is null, generating...");
 
-      tokenTopolgy = new Area(zone.getTopology());
+      tokenTopology = new Area(zone.getTopology());
       List<Token> vblTokens =
           MapTool.getFrame().getCurrentZoneRenderer().getZone().getTokensWithVBL();
 
       for (Token vblToken : vblTokens) {
-        tokenTopolgy.add(vblToken.getTransformedVBL());
+        tokenTopology.add(vblToken.getTransformedVBL());
       }
 
-      topologyTree = new AreaTree(tokenTopolgy);
+      topologyTree = new AreaTree(tokenTopology);
     } else if (topologyTree == null) {
       topologyTree = new AreaTree(zone.getTopology());
     }
@@ -138,6 +169,14 @@ public synchronized AreaTree getTopologyTree(boolean useTokenVBL) {
   // return topologyAreaData;
   // }
 
+  /**
+   * Return the lightSourceArea of the lightSourceToken, for the baseToken's sight type. Fill the
+   * lightSourceCache entry if null.
+   *
+   * @param baseToken the base token. Used to get the appropriate sight type.
+   * @param lightSourceToken the token holding the light sources.
+   * @return the lightSourceArea.
+   */
   private TreeMap<Double, Area> getLightSourceArea(Token baseToken, Token lightSourceToken) {
     Map<String, TreeMap<Double, Area>> areaBySightMap =
         lightSourceCache.get(lightSourceToken.getId());
@@ -182,16 +221,47 @@ private TreeMap<Double, Area> getLightSourceArea(Token baseToken, Token lightSou
     return lightSourceAreaMap;
   }
 
+  /**
+   * Calculate the area visible by a sight type for a given light, and put the lights in
+   * drawableLightCache and brightLightCache.
+   *
+   * @param lightSource the personal light source.
+   * @param lightSourceToken the token holding the light source.
+   * @param sight the sight type.
+   * @param direction the direction of the light source.
+   * @return the area visible.
+   */
   private Area calculatePersonalLightSourceArea(
       LightSource lightSource, Token lightSourceToken, SightType sight, Direction direction) {
     return calculateLightSourceArea(lightSource, lightSourceToken, sight, direction, true);
   }
 
+  /**
+   * Calculate the area visible by a sight type for a given light, and put the lights in
+   * drawableLightCache and brightLightCache.
+   *
+   * @param lightSource the light source. Not a personal light.
+   * @param lightSourceToken the token holding the light source.
+   * @param sight the sight type.
+   * @param direction the direction of the light source.
+   * @return the area visible.
+   */
   private Area calculateLightSourceArea(
       LightSource lightSource, Token lightSourceToken, SightType sight, Direction direction) {
     return calculateLightSourceArea(lightSource, lightSourceToken, sight, direction, false);
   }
 
+  /**
+   * Calculate the area visible by a sight type for a given lightSource, and put the lights in
+   * drawableLightCache and brightLightCache.
+   *
+   * @param lightSource the light source. Not a personal light.
+   * @param lightSourceToken the token holding the light source.
+   * @param sight the sight type.
+   * @param direction the direction of the light source.
+   * @param isPersonalLight is the light a personal light?
+   * @return the area visible.
+   */
   private Area calculateLightSourceArea(
       LightSource lightSource,
       Token lightSourceToken,
@@ -268,6 +338,12 @@ private Area calculateLightSourceArea(
     return visibleArea;
   }
 
+  /**
+   * Return the token visible area from tokenVisionCache. If null, create it.
+   *
+   * @param token the token to get the visible area of.
+   * @return the visible area of a token, including the effect of other lights.
+   */
   public Area getVisibleArea(Token token) {
     // Sanity
     if (token == null || !token.getHasSight()) {
@@ -461,6 +537,12 @@ public TreeMap<Double, Area> call() throws Exception {
     }
   }
 
+  /**
+   * Get the lists of drawable light from lightSourceMap.
+   *
+   * @param type the type of lights to get.
+   * @return the list of drawable lights of the given type.
+   */
   public List<DrawableLight> getLights(LightSource.Type type) {
     List<DrawableLight> lightList = new LinkedList<DrawableLight>();
     if (lightSourceMap.get(type) != null) {
@@ -511,6 +593,7 @@ public List<DrawableLight> getLights(LightSource.Type type) {
     return lightList;
   }
 
+  /** Find the light sources from all appropriate tokens, and store them in lightSourceMap. */
   private void findLightSources() {
     lightSourceMap.clear();
 
@@ -534,6 +617,11 @@ private void findLightSources() {
     }
   }
 
+  /**
+   * Get the drawable lights from the drawableLightCache.
+   *
+   * @return the set of drawable lights.
+   */
   public Set<DrawableLight> getDrawableLights() {
     Set<DrawableLight> lightSet = new HashSet<DrawableLight>();
 
@@ -545,6 +633,11 @@ public Set<DrawableLight> getDrawableLights() {
     return lightSet;
   }
 
+  /**
+   * Get the drawable lights from the brightLightCache.
+   *
+   * @return the set of bright lights.
+   */
   public Set<Area> getBrightLights() {
     Set<Area> lightSet = new HashSet<Area>();
     // MJ: There seems to be contention for this cache, but that looks inconspicuous enough to
@@ -559,6 +652,10 @@ public Set<Area> getBrightLights() {
     return lightSet;
   }
 
+  /**
+   * Clear the tokenVisibleAreaCache, tokenVisionCache, lightSourceCache, visibleAreaMap,
+   * drawableLightCache, and brightLightCache.
+   */
   public void flush() {
     tokenVisibleAreaCache.clear();
     tokenVisionCache.clear();
@@ -568,6 +665,13 @@ public void flush() {
     brightLightCache.clear();
   }
 
+  /**
+   * Flush the ZoneView cache of the token. Remove token from tokenVisibleAreaCache,
+   * drawableLightCache, and brightLightCache. Always clear tokenVisionCache, visibleAreaMap, and
+   * lightSourceCache.
+   *
+   * @param token the token to flush.
+   */
   public void flush(Token token) {
     boolean hadLightSource = lightSourceCache.get(token.getId()) != null;
 
@@ -593,6 +697,11 @@ public void flush(Token token) {
     tokenVisionCache.clear();
   }
 
+  /**
+   * Construct the visibleAreaMap entry for a player view.
+   *
+   * @param view the player view.
+   */
   private void calculateVisibleArea(PlayerView view) {
     if (visibleAreaMap.get(view) != null
         && visibleAreaMap.get(view).visibleArea.getBounds().getCenterX() != 0.0d) {
@@ -645,8 +754,11 @@ public boolean matchToken(Token t) {
     // "ms");
   }
 
-  ////
-  // MODEL CHANGE LISTENER
+  /**
+   * MODEL CHANGE LISTENER for events TOKEN_CHANGED, TOKEN_REMOVED, TOKEN_ADDED.
+   *
+   * @param event the event.
+   */
   @SuppressWarnings("unchecked")
   public void modelChanged(ModelChangeEvent event) {
     Object evt = event.getEvent();
@@ -708,16 +820,20 @@ public void modelChanged(ModelChangeEvent event) {
         lightSourceCache.clear();
         visibleAreaMap.clear();
         topologyTree = null;
-        tokenTopolgy = null;
+        tokenTopology = null;
         tokenVisibleAreaCache.clear();
+
         // topologyAreaData = null; // Jamz: This isn't used, probably never completed code.
       }
     }
   }
 
   /**
-   * @param tokens the list of token
-   * @return if the token has VBL or not
+   * Update lightSourceMap with the light sources of the tokens, and clear visibleAreaMap if one of
+   * the tokens has sight.
+   *
+   * @param tokens the list of tokens
+   * @return if one of the token has VBL or not
    */
   private boolean processTokenAddChangeEvent(List<Token> tokens) {
     boolean hasSight = false;
@@ -750,6 +866,7 @@ private boolean processTokenAddChangeEvent(List<Token> tokens) {
     return hasVBL;
   }
 
+  /** Has a single field: the visibleArea area */
   private static class VisibleAreaMeta {
     Area visibleArea;
   }
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/vbl/AreaTree.java b/src/main/java/net/rptools/maptool/client/ui/zone/vbl/AreaTree.java
index a258081a74..4f226adf4d 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/vbl/AreaTree.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/vbl/AreaTree.java
@@ -23,11 +23,19 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/** Class digesting a VBL area into an AreaOcean. */
 public class AreaTree {
   private static final Logger log = LogManager.getLogger(AreaTree.class);
+  /** The original area digested. */
   private AreaOcean theOcean;
-  private Area theArea; // in case we want to return the original area undigested
+  /** The original area, in case we want to return the original area undigested */
+  private Area theArea;
 
+  /**
+   * Digest the area and store it in theOcean.
+   *
+   * @param area the area to digest.
+   */
   public AreaTree(Area area) {
     digest(area);
   }
diff --git a/src/main/java/net/rptools/maptool/client/ui/zone/vbl/TokenVBL.java b/src/main/java/net/rptools/maptool/client/ui/zone/vbl/TokenVBL.java
index 58562da38d..becff5517e 100644
--- a/src/main/java/net/rptools/maptool/client/ui/zone/vbl/TokenVBL.java
+++ b/src/main/java/net/rptools/maptool/client/ui/zone/vbl/TokenVBL.java
@@ -41,8 +41,8 @@ public class TokenVBL {
    *
    * @author Jamz
    * @since 1.4.1.6
-   * @param token
-   * @param alphaSensitivity
+   * @param token the token
+   * @param alphaSensitivity the alpha sensitivity of the VBL area
    * @return Area
    */
   public static Area createVblArea(Token token, int alphaSensitivity) {
@@ -62,6 +62,7 @@ public static Area createVblArea(Token token, int alphaSensitivity) {
    * @param renderer Reference to the ZoneRenderer
    * @param area A valid Area containing VBL polygons
    * @param erase Set to true to erase the VBL, otherwise draw it
+   * @return the untouched area if the renderer is null, and null otherwise
    */
   public static Area renderVBL(ZoneRenderer renderer, Area area, boolean erase) {
     if (renderer == null) return area;
@@ -197,6 +198,14 @@ public static Area getVBL_underToken(ZoneRenderer renderer, Token token) {
     return newTokenVBL;
   }
 
+  /**
+   * Create a VBL area from a bufferedImage and alphaSensitity. The area is created by combining
+   * vblRectangle where the alpha of the image is greater or equal to the sensitivity.
+   *
+   * @param image the buffered image.
+   * @param alphaSensitivity the alphaSensitivity.
+   * @return the area.
+   */
   private static Area createVblArea(BufferedImage image, int alphaSensitivity) {
     // Assumes all colors form the VBL Area, eg everything except transparent pixels with alpha
     // >=
diff --git a/src/main/java/net/rptools/maptool/model/BaseModel.java b/src/main/java/net/rptools/maptool/model/BaseModel.java
index 4d193047ca..de0ad2728d 100644
--- a/src/main/java/net/rptools/maptool/model/BaseModel.java
+++ b/src/main/java/net/rptools/maptool/model/BaseModel.java
@@ -23,14 +23,28 @@ public class BaseModel {
   private transient List<ModelChangeListener> listenerList =
       new CopyOnWriteArrayList<ModelChangeListener>();
 
+  /**
+   * Add the listener to the listenerList.
+   *
+   * @param listener the ModelChangeListener to add.
+   */
   public void addModelChangeListener(ModelChangeListener listener) {
     listenerList.add(listener);
   }
-
+  /**
+   * Remove the listener from the listenerList.
+   *
+   * @param listener the ModelChangeListener to remove.
+   */
   public void removeModelChangeListener(ModelChangeListener listener) {
     listenerList.remove(listener);
   }
 
+  /**
+   * Send the event to each listener in listenerList
+   *
+   * @param event the event
+   */
   protected void fireModelChangeEvent(ModelChangeEvent event) {
 
     for (ModelChangeListener listener : listenerList) {
@@ -38,6 +52,11 @@ protected void fireModelChangeEvent(ModelChangeEvent event) {
     }
   }
 
+  /**
+   * Create a new listenerList, and returns this.
+   *
+   * @return this.
+   */
   protected Object readResolve() {
     listenerList = new CopyOnWriteArrayList<ModelChangeListener>();
     return this;
diff --git a/src/main/java/net/rptools/maptool/model/Campaign.java b/src/main/java/net/rptools/maptool/model/Campaign.java
index 7698a0b686..30cd597a56 100644
--- a/src/main/java/net/rptools/maptool/model/Campaign.java
+++ b/src/main/java/net/rptools/maptool/model/Campaign.java
@@ -240,7 +240,8 @@ public Map<String, List<TokenProperty>> getTokenTypeMap() {
    * Convenience method that calls {@link #getSightTypeMap()} and returns the value for the key
    * <code>type</code>.
    *
-   * @return
+   * @param type the String corresponding to the SightType.
+   * @return the SightType.
    */
   public SightType getSightType(String type) {
     return getSightTypeMap()
diff --git a/src/main/java/net/rptools/maptool/model/ExposedAreaMetaData.java b/src/main/java/net/rptools/maptool/model/ExposedAreaMetaData.java
index c97a4027e4..d4beee7ab3 100644
--- a/src/main/java/net/rptools/maptool/model/ExposedAreaMetaData.java
+++ b/src/main/java/net/rptools/maptool/model/ExposedAreaMetaData.java
@@ -16,7 +16,9 @@
 
 import java.awt.geom.Area;
 
+/** Stores the exposed area of a token. */
 public class ExposedAreaMetaData {
+  /** Area exposed so far. */
   private Area exposedAreaHistory;
 
   public ExposedAreaMetaData() {
diff --git a/src/main/java/net/rptools/maptool/model/LightSource.java b/src/main/java/net/rptools/maptool/model/LightSource.java
index 27cef529b0..aacb6ca3e0 100644
--- a/src/main/java/net/rptools/maptool/model/LightSource.java
+++ b/src/main/java/net/rptools/maptool/model/LightSource.java
@@ -93,6 +93,7 @@ public void remove(Light source) {
     getLightList().remove(source);
   }
 
+  /** @return the lightList of the LightSource */
   public List<Light> getLightList() {
     if (lightList == null) {
       lightList = new LinkedList<Light>();
diff --git a/src/main/java/net/rptools/maptool/model/SightType.java b/src/main/java/net/rptools/maptool/model/SightType.java
index 0788e7fc61..5afdfe5eb5 100644
--- a/src/main/java/net/rptools/maptool/model/SightType.java
+++ b/src/main/java/net/rptools/maptool/model/SightType.java
@@ -125,6 +125,13 @@ public int getArc() {
     return arc;
   }
 
+  /**
+   * Get the shapedArea of a token's vision in a zone
+   *
+   * @param token the token.
+   * @param zone the zone.
+   * @return the Area of the vision shape.
+   */
   public Area getVisionShape(Token token, Zone zone) {
     return zone.getGrid()
         .getShapedArea(getShape(), token, getDistance(), getArc(), getOffset(), scaleWithToken);
diff --git a/src/main/java/net/rptools/maptool/model/Token.java b/src/main/java/net/rptools/maptool/model/Token.java
index 608af8cc3e..6369a166ea 100644
--- a/src/main/java/net/rptools/maptool/model/Token.java
+++ b/src/main/java/net/rptools/maptool/model/Token.java
@@ -820,7 +820,7 @@ public void removeLightSource(LightSource source) {
     }
   }
 
-  // My Addition
+  /** Clear the lightSourceList */
   public void clearLightSources() {
     if (lightSourceList == null) {
       return;
@@ -828,8 +828,6 @@ public void clearLightSources() {
     lightSourceList = null;
   }
 
-  // End My Addition
-
   public boolean hasLightSource(LightSource source) {
     if (lightSourceList == null) {
       return false;
@@ -845,6 +843,7 @@ public boolean hasLightSource(LightSource source) {
     return false;
   }
 
+  /** Return false if lightSourceList is null or empty, and true otherwise */
   public boolean hasLightSources() {
     return lightSourceList != null && !lightSourceList.isEmpty();
   }
@@ -1122,6 +1121,7 @@ public void setVisible(boolean visible) {
     this.isVisible = visible;
   }
 
+  /** @return isVisible */
   public boolean isVisible() {
     return isVisible;
   }
@@ -1161,11 +1161,17 @@ public int getAlphaSensitivity() {
     return vblAlphaSensitivity;
   }
 
+  /**
+   * Set the VBL of the token. If vbl null, set vblAplphaSensitivity to -1.
+   *
+   * @param vbl the VBL to set.
+   */
   public void setVBL(Area vbl) {
     this.vbl = vbl;
     if (vbl == null) vblAlphaSensitivity = -1;
   }
 
+  /** Return the vbl area of the token */
   public Area getVBL() {
     return vbl;
   }
@@ -1261,9 +1267,13 @@ public Area getTransformedVBL(Area areaToTransform) {
     return new Area(atArea.createTransformedShape(areaToTransform));
   }
 
+  /**
+   * Return the existence of the token's VBL
+   *
+   * @return rue if the token's vbl is null, and false otherwise
+   */
   public boolean hasVBL() {
-    if (vbl != null) return true;
-    else return false;
+    return vbl != null;
   }
 
   public void setIsAlwaysVisible(boolean isAlwaysVisible) {
@@ -1322,6 +1332,7 @@ public Rectangle getBounds(Zone zone) {
     return footprintBounds;
   }
 
+  /** @return the String of the sightType */
   public String getSightType() {
     return sightType;
   }
@@ -2053,6 +2064,7 @@ public void setHeroLabData(HeroLabData heroLabData) {
    * @param parameters An array of parameters
    */
   public void updateProperty(Zone zone, String methodName, Object[] parameters) {
+    boolean lightChanged = false;
     switch (methodName) {
       case "setState":
         setState(parameters[0].toString(), parameters[1]);
@@ -2075,23 +2087,19 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
       case "setLayerShape":
         setLayer((Zone.Layer) parameters[0]);
         setShape((TokenShape) parameters[1]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setShape":
         setShape((TokenShape) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setSnapToScale":
         setSnapToScale((Boolean) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setSnapToGrid":
         setSnapToGrid((Boolean) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setFootprint":
+        setSnapToScale(true);
         setFootprint((Grid) parameters[0], (TokenFootprint) parameters[1]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setProperty":
         setProperty(parameters[0].toString(), parameters[1].toString());
@@ -2104,8 +2112,8 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
         zone.sortZOrder(); // update new ZOrder
         break;
       case "setFacing":
+        if (hasLightSources()) lightChanged = true;
         setFacing((Integer) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "clearAllOwners":
         clearAllOwners();
@@ -2117,17 +2125,17 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
         addOwner(parameters[0].toString());
         break;
       case "setScaleX":
+        setSnapToScale(false);
         setScaleX((double) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setScaleY":
+        setSnapToScale(false);
         setScaleY((double) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setScaleXY":
+        setSnapToScale(false);
         setScaleX((double) parameters[0]);
         setScaleY((double) parameters[1]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setNotes":
         setNotes(parameters[0].toString());
@@ -2136,17 +2144,17 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
         setGMNotes(parameters[0].toString());
         break;
       case "setX":
+        if (hasLightSources()) lightChanged = true;
         setX((int) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setY":
+        if (hasLightSources()) lightChanged = true;
         setY((int) parameters[0]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setXY":
+        if (hasLightSources()) lightChanged = true;
         setX((int) parameters[0]);
         setY((int) parameters[1]);
-        if (hasVBL()) zone.tokenTopologyChanged(); // update VBL if token has any
         break;
       case "setHaloColor":
         setHaloColor((Color) parameters[0]);
@@ -2177,6 +2185,9 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
         break;
       case "setVBL":
         setVBL((Area) parameters[0]);
+        if (!hasVBL()) { // if VBL removed
+          zone.tokenTopologyChanged(); // if token lost VBL, TOKEN_CHANGED won't update topology
+        }
         break;
       case "setImageAsset":
         setImageAsset((String) parameters[0], (MD5Key) parameters[1]);
@@ -2188,21 +2199,27 @@ public void updateProperty(Zone zone, String methodName, Object[] parameters) {
         setCharsheetImage((MD5Key) parameters[0]);
         break;
       case "clearLightSources":
+        if (hasLightSources()) lightChanged = true;
         clearLightSources();
         break;
       case "removeLightSource":
+        if (hasLightSources()) lightChanged = true;
         removeLightSource((LightSource) parameters[0]);
         break;
       case "addLightSource":
+        lightChanged = true;
         addLightSource((LightSource) parameters[0], (Direction) parameters[1]);
         break;
       case "setHasSight":
+        if (hasLightSources()) lightChanged = true;
         setHasSight((boolean) parameters[0]);
         break;
       case "setSightType":
+        if (hasLightSources()) lightChanged = true;
         setSightType((String) parameters[0]);
         break;
     }
-    zone.tokenChanged(this); // fireModelChangeEvent Event.TOKEN_CHANGED
+    if (lightChanged) getZoneRenderer().flushLight(); // flush lights if it changed
+    zone.tokenChanged(this); // fire Event.TOKEN_CHANGED, which updates topology if token has VBL
   }
 }
diff --git a/src/main/java/net/rptools/maptool/model/Zone.java b/src/main/java/net/rptools/maptool/model/Zone.java
index d8d38dfacd..8a9f55fd4d 100644
--- a/src/main/java/net/rptools/maptool/model/Zone.java
+++ b/src/main/java/net/rptools/maptool/model/Zone.java
@@ -61,12 +61,14 @@
 public class Zone extends BaseModel {
   private static final Logger log = LogManager.getLogger(Zone.class);
 
+  /** The vision type (OFF, DAY, NIGHT). */
   public enum VisionType {
     OFF,
     DAY,
     NIGHT
   }
 
+  /** Event types for the listeners. */
   public enum Event {
     TOKEN_ADDED,
     TOKEN_REMOVED,
@@ -83,6 +85,7 @@ public enum Event {
     BOARD_CHANGED
   }
 
+  /** The type of layer (TOKEN, GM, OBJECT or BACKGROUND). */
   public enum Layer {
     TOKEN("Token"),
     GM("Hidden"),
@@ -100,9 +103,10 @@ public String toString() {
       return displayName;
     }
 
-    // A simple interface to allow layers to be turned on/off
+    /** A simple interface to allow layers to be turned on/off */
     private boolean drawEnabled = true;
 
+    /** @return drawEnabled */
     public boolean isEnabled() {
       return drawEnabled;
     }
@@ -112,6 +116,7 @@ public void setEnabled(boolean enabled) {
     }
   }
 
+  /** The selection type (PC, NPC, ALL, GM). */
   public enum TokenSelection {
     PC,
     NPC,
@@ -150,17 +155,24 @@ public enum TokenSelection {
   private List<DrawnElement> backgroundDrawables = new LinkedList<DrawnElement>();
 
   private final Map<GUID, Label> labels = new LinkedHashMap<GUID, Label>();
+  /** Map each token GUID to the corresponding token. */
   private final Map<GUID, Token> tokenMap = new HashMap<GUID, Token>();
+  /** Map each token GUID to its exposed area metadata */
   private Map<GUID, ExposedAreaMetaData> exposedAreaMeta = new HashMap<GUID, ExposedAreaMetaData>();
+
+  /** Token list ordered by Z. */
   private final List<Token> tokenOrderedList = new LinkedList<Token>();
 
   private InitiativeList initiativeList = new InitiativeList(this);
 
+  /** The global exposed area. */
   private Area exposedArea = new Area();
+
   private boolean hasFog;
   private DrawablePaint fogPaint;
   private transient UndoPerZone undo;
 
+  /** The VBL topology of the zone. Does not include token VBL. */
   private Area topology = new Area();
 
   // The 'board' layer, at the very bottom of the layer stack.
@@ -181,7 +193,9 @@ public enum TokenSelection {
   private String name;
   private boolean isVisible;
 
+  /** The VisionType of the zone. OFF, DAY or NIGHT. */
   private VisionType visionType = VisionType.OFF;
+
   private TokenSelection tokenSelection = TokenSelection.ALL;
 
   // These are transitionary properties, very soon the width and height won't matter
@@ -240,7 +254,7 @@ public void setTokenSelection(TokenSelection tokenSelection) {
     this.tokenSelection = tokenSelection;
   }
 
-  /** Returns the distance in map pixels at a 1:1 zoom */
+  /** @return the distance in map pixels at a 1:1 zoom */
   public int getTokenVisionInPixels() {
     if (tokenVisionDistance == 0) {
       // TODO: This is here to provide transition between pre 1.3b19 an 1.3b19. Remove later
@@ -258,6 +272,7 @@ public String toString() {
     return name;
   }
 
+  /** @return name of the zone */
   public String getName() {
     return name;
   }
@@ -467,6 +482,8 @@ public void setGridColor(int color) {
   /**
    * Board pseudo-object. Not making full object since this will change when new layer model is
    * created
+   *
+   * @return has the board changed?
    */
   public boolean isBoardChanged() {
     return boardChanged;
@@ -556,9 +573,9 @@ public void setHasFog(boolean flag) {
    *       (with HasSight==true) and return intersection of point with the combined area.
    * </ol>
    *
-   * @param point
-   * @param view
-   * @return
+   * @param point the ZonePoint to test.
+   * @param view the PlayerView.
+   * @return is the point visible?
    */
   public boolean isPointVisible(ZonePoint point, PlayerView view) {
     if (!hasFog() || view.isGMView()) {
@@ -602,8 +619,8 @@ public boolean isEmpty() {
    *   <li>If the token's bounds intersect the exposed area for this map, return <code>true</code>.
    * </ol>
    *
-   * @param token
-   * @return
+   * @param token the token to test.
+   * @return is the token visible?
    */
   public boolean isTokenVisible(Token token) {
     if (token == null) {
@@ -691,24 +708,41 @@ public void clearTopology() {
     fireModelChangeEvent(new ModelChangeEvent(this, Event.TOPOLOGY_CHANGED));
   }
 
+  /**
+   * Add the area to the topology, and fire the event TOPOLOGY_CHANGED
+   *
+   * @param area the area
+   */
   public void addTopology(Area area) {
     topology.add(area);
     fireModelChangeEvent(new ModelChangeEvent(this, Event.TOPOLOGY_CHANGED));
   }
 
+  /**
+   * Subtract the area from the topology, and fire the event TOPOLOGY_CHANGED
+   *
+   * @param area the area
+   */
   public void removeTopology(Area area) {
     topology.subtract(area);
     fireModelChangeEvent(new ModelChangeEvent(this, Event.TOPOLOGY_CHANGED));
   }
 
+  /** Fire the event TOPOLOGY_CHANGED. */
   public void tokenTopologyChanged() {
     fireModelChangeEvent(new ModelChangeEvent(this, Event.TOPOLOGY_CHANGED));
   }
 
+  /** @return the topology of the zone */
   public Area getTopology() {
     return topology;
   }
 
+  /**
+   * Fire the event TOKEN_CHANGED
+   *
+   * @param token the token that changed
+   */
   public void tokenChanged(Token token) {
     fireModelChangeEvent(new ModelChangeEvent(this, Event.TOKEN_CHANGED, token));
   }
@@ -924,7 +958,7 @@ public ZonePoint getNearestVertex(ZonePoint point) {
    * the result is returned.
    *
    * @param view holds whether or not tokens are selected
-   * @return
+   * @return the exposed area
    */
   public Area getExposedArea(PlayerView view) {
     Area combined = new Area(exposedArea);
@@ -1228,7 +1262,10 @@ public Token getToken(GUID id) {
     return tokenMap.get(id);
   }
 
-  /** Returns the first token with a given name. The name is matched case-insensitively. */
+  /**
+   * @param name the name of the token.
+   * @return the first token with a given name. The name is matched case-insensitively.
+   */
   public Token getTokenByName(String name) {
     for (Token token : getAllTokens()) {
       if (StringUtil.isEmpty(token.getName())) {
@@ -1244,7 +1281,7 @@ public Token getTokenByName(String name) {
   /**
    * Looks for the given identifier as a token name, token GM name, or GUID, in that order.
    *
-   * @param identifier
+   * @param identifier the String identifier of the token
    * @return token that matches the identifier or <code>null</code>
    */
   public Token resolveToken(String identifier) {
@@ -1262,7 +1299,10 @@ public Token resolveToken(String identifier) {
     return token;
   }
 
-  /** Returns the first token with a given GM name. The name is matched case-insensitively. */
+  /**
+   * @param name the GM name of the token.
+   * @return the first token with a given GM name. The name is matched case-insensitively.
+   */
   public Token getTokenByGMName(String name) {
     for (Token token : getAllTokens()) {
       if (StringUtil.isEmpty(token.getGMName())) {
@@ -1363,7 +1403,7 @@ public List<Token> removeTokens(List<Token> tokensToKeep, List<Token> tokensToRe
     return Collections.unmodifiableList(originalList);
   }
 
-  /** This is the list of non-stamp tokens, both pc and npc */
+  /** @return list of non-stamp tokens, both pc and npc */
   public List<Token> getTokens() {
     return getTokens(true);
   }
@@ -1482,7 +1522,7 @@ public boolean matchToken(Token t) {
    * @author updated by Jamz
    * @since updated 1.4.1.0
    * @param p the player
-   * @return
+   * @return the list of tokens
    */
   public List<Token> getOwnedTokensWithSight(Player p) {
     return getTokensFiltered(
@@ -1516,7 +1556,7 @@ public boolean matchToken(Token t) {
         });
   }
 
-  /** Returns PCs tokens with sight. For FogUtil.exposePCArea to skip sight test. */
+  /** @return list of PCs tokens with sight. For FogUtil.exposePCArea to skip sight test. */
   public List<Token> getPlayerTokensWithSight() {
     return getTokensFiltered(
         new Filter() {
@@ -1529,6 +1569,8 @@ public boolean matchToken(Token t) {
   /**
    * Jamz: Get a list of all tokens with sight that are either PC tokens or NPC Tokens "Owned by
    * All", or "Owned" by the current player; in theory, NPC tokens the Player control.
+   *
+   * @return the list of tokens with sight.
    */
   public List<Token> getTokensOwnedByAllWithSight() {
     return getTokensFiltered(
@@ -1601,12 +1643,15 @@ public int findFreeNumber(String tokenBaseName, boolean checkDm) {
     return lastUsed;
   }
 
+  /** Interface for matchToken. */
   public static interface Filter {
     public boolean matchToken(Token t);
   }
 
+  /** Construct a new TokenZOrderComparator. */
   public static final Comparator<Token> TOKEN_Z_ORDER_COMPARATOR = new TokenZOrderComparator();
 
+  /** The class used to compare the Zorder of two tokens. */
   public static class TokenZOrderComparator implements Comparator<Token> {
     @Override
     public int compare(Token o1, Token o2) {
@@ -1624,6 +1669,8 @@ public int compare(Token o1, Token o2) {
   /**
    * Replaces the static TOKEN_Z_ORDER_COMPARATOR comparator with instantiated version so that grid
    * is available and can access token footprint. Only used when Rendering just Figure Tokens.
+   *
+   * @return the token comparator.
    */
   public Comparator<Token> getFigureZOrderComparator() {
     return new Comparator<Token>() {
@@ -1658,11 +1705,15 @@ public int compare(Token o1, Token o2) {
     };
   }
 
+  /**
+   * If set size return the footprint, otherwise return bounding box. Figure tokens are designed for
+   * set sizes so we need to approximate free size tokens
+   *
+   * @param t the token to get center of.
+   * @return the center of the footprint / bounding box.
+   */
   private int getFigureZOrder(Token t) {
-    /**
-     * If set size return the footprint, otherwise return bounding box. Figure tokens are designed
-     * for set sizes so we need to approximate free size tokens
-     */
+
     Rectangle b1 =
         t.isSnapToScale() ? t.getFootprint(getGrid()).getBounds(getGrid()) : t.getBounds(getZone());
     /**
@@ -1675,6 +1726,7 @@ private int getFigureZOrder(Token t) {
     return bottom - centre;
   }
 
+  /** @return this */
   private Zone getZone() {
     return this;
   }
@@ -1819,6 +1871,7 @@ public boolean matchToken(Token token) {
     return this;
   }
 
+  /** @return the exposedAreaMeta. */
   public Map<GUID, ExposedAreaMetaData> getExposedAreaMetaData() {
     if (exposedAreaMeta == null) {
       exposedAreaMeta = new HashMap<GUID, ExposedAreaMetaData>();