Javadoc fixes.

Author: Mike Pope

src/net/sf/freecol/FreeCol.java

@@ -1210,6 +1210,7 @@ public static int getMetaServerPort() {
      * Set the meta-server location.
      *
      * @param arg The new meta-server location in HOST:PORT format.
+     * @return True if the location was set.
      */
     private static boolean setMetaServer(String arg) {
         String[] s = arg.split(":");

src/net/sf/freecol/client/ClientOptions.java

@@ -614,7 +614,7 @@ public Comparator<Colony> getColonyComparator() {
     /**
      * Get the colony comparator identified by type.
      *
-     * @param The colony comparator option integer value.
+     * @param type The colony comparator option integer value.
      * @return The corresponding colony {@code Comparator}.
      */
     private static Comparator<Colony> getColonyComparatorInternal(int type) {
@@ -750,6 +750,14 @@ private void addOptionGroup(String id, String gr) {
         }
     }*/
 
+    /**
+     * Add a new range option.
+     *
+     * @param id The option identifier.
+     * @param gr The group identifier.
+     * @param rank The option rank.
+     * @param entries The options in the range.
+     */
     private void addRangeOption(String id, String gr, int rank,
                                 Map<Integer, String> entries) {
         if (!hasOption(id, RangeOption.class)) {
@@ -764,6 +772,13 @@ private void addRangeOption(String id, String gr, int rank,
         }
     }
 
+    /**
+     * Add a new text option.
+     *
+     * @param id The option identifier.
+     * @param gr The group identifier.
+     * @param val The the text value.
+     */
     private void addTextOption(String id, String gr, String val) {
         if (!hasOption(id, TextOption.class)) {
             TextOption op = new TextOption(id, null);

src/net/sf/freecol/client/FreeColClient.java

@@ -909,8 +909,10 @@ public synchronized void login(boolean inGame, Game game, Player player,
      * Log this client out.
      *
      * Called when the ConnectController processes a logout.
+     *
+     * @param inGame Whether the server is in-game.
      */
-    public synchronized void logout(boolean inGame) {
+    public synchronized void logout(@SuppressWarnings("unused") boolean inGame) {
         this.loggedIn = false;
         changeClientState(inGame);
         setGame(null);

src/net/sf/freecol/client/control/ConnectController.java

@@ -54,8 +54,6 @@
 
 /**
  * The controller responsible for starting a server and connecting to it.
- * {@link PreGameInputHandler} will be set as the input handler when a
- * successful login has been completed,
  */
 public final class ConnectController extends FreeColClientHolder {
 
@@ -238,9 +236,10 @@ public boolean requestLogin(String user, String host, int port) {
      * game should include a map and a full complement of players,
      * including ours.
      *
-     * Otherwise we may still need to select a nation, and
-     * optionally change game or map options (using several
-     * possible messages).  {@link StartGamePanel} does this.
+     * Otherwise we may still need to select a nation, and optionally
+     * change game or map options (using several possible messages).
+     * {@link net.sf.freecol.client.gui.panel.StartGamePanel} does
+     * this.
      *
      * When all the parameters are in place and all players are
      * ready (trivially true in single player, needs checking in
@@ -300,7 +299,7 @@ public void login(ServerState state, Game game, String user,
     // They all ultimately have to establish a connection to the server,
     // and get the game from there, which is done in {@link #login()}.
     // Control then effectively transfers to the handler for the login
-    // message in {@link PreGameInputHandler}.
+    // message.
     //
 
     /**

src/net/sf/freecol/client/control/InGameController.java

@@ -2360,6 +2360,8 @@ public boolean abandonColony(Colony colony) {
 
     /**
      * Handle an addPlayer message.
+     *
+     * @param players The {@code Player}s to add.
      */
     public void addPlayerHandler(List<Player> players) {
         getGame().addPlayers(players);
@@ -2901,6 +2903,8 @@ public boolean clearSpeciality(Unit unit) {
 
     /**
      * Close any open GUI menus.
+     *
+     * @param panel The identifier for the panel to close.
      */
     public void closeHandler(String panel) {
         getGUI().closePanel(panel);

src/net/sf/freecol/client/control/MapTransform.java

@@ -45,10 +45,10 @@ public abstract class MapTransform {
     public abstract void transform(Tile t);
 
     /**
-     * A panel with information about this transformation.
-     * This panel is currently displayed on the
-     * {@link InfoPanel} when selected, but might be
-     * used elsewhere as well.
+     * A panel with information about this transformation.  This panel
+     * is currently displayed on the
+     * {@link net.sf.freecol.client.gui.panel.InfoPanel} when selected,
+     * but might be used elsewhere as well.
      *
      * @return The panel or {@code null} if no panel
      *      has been set.

src/net/sf/freecol/client/control/PreGameController.java

@@ -71,6 +71,8 @@ public PreGameController(FreeColClient freeColClient) {
 
     /**
      * Handle an addPlayer message.
+     *
+     * @param players The {@code Player}s to add.
      */
     public void addPlayerHandler(List<Player> players) {
         getGame().addPlayers(players);
@@ -102,6 +104,9 @@ public void chatHandler(Player player, String message, boolean pri) {
 
     /**
      * Handle an error.
+     *
+     * @param template A {@code StringTemplate} describing the error.
+     * @param message A backup string describing the error.
      */
     public void errorHandler(StringTemplate template, String message) {
         getGUI().showErrorMessage(template, message);

src/net/sf/freecol/client/gui/Canvas.java

@@ -512,6 +512,7 @@ public void setDragPoint(int x, int y) {
      *
      * @param x The new mouse x position.
      * @param y The new mouse y position.
+     * @return True if the mouse has been dragged.
      */
     public boolean isDrag(int x, int y) {
         final Point drag = getDragPoint();
@@ -1206,7 +1207,9 @@ public void displayChat(GUIMessage message) {
     /**
      * Tells that a chat message was received.
      *
+     * @param senderName The sender.
      * @param message The chat message.
+     * @param privateChat True if this is a private message.
      */
     public void displayStartChat(String senderName, String message,
                                  boolean privateChat) {
@@ -2539,8 +2542,6 @@ public void showTilePopup(Tile tile) {
      * Display the trade route input panel for a given trade route.
      *
      * @param newRoute The {@code TradeRoute} to display.
-     * @param callBack The {@code Runnable} that is run when the
-     *     panel closes.
      * @return The {@code TradeRouteInputPanel}.
      */
     public TradeRouteInputPanel showTradeRouteInputPanel(TradeRoute newRoute) {

src/net/sf/freecol/client/gui/GUI.java

@@ -1134,8 +1134,6 @@ private final void showSettlement(Settlement settlement) {
      * to a given player.
      *
      * @param tile The {@code Tile} to check for settlements.
-     * @param foriegn If true, use the foreign settlement functionality
-     *     for colonies.
      */
     public final void showTileSettlement(Tile tile) {
         if (tile == null) return;
@@ -1354,6 +1352,9 @@ public void executeWithUnitOutForAnimation(Unit unit, Tile sourceTile,
     /**
      * Get the animation position.
      *
+     * @param labelWidth The width of the label.
+     * @param labelHeight The height of the label.
+     * @param tileP The position of the {@code Tile} on the screen.
      * @return A point on the map to place a unit for movement.
      */
     public Point getAnimationPosition(int labelWidth, int labelHeight,
@@ -1562,7 +1563,7 @@ public void clearGotoPath() {}
     /**
      * Perform an immediate goto to a tile with the active unit.
      *
-     * Called from {@see TilePopup}.
+     * Called from {@link TilePopup}.
      *
      * @param tile The {@code Tile} to go to.
      */
@@ -1571,7 +1572,7 @@ public void performGoto(Tile tile) {}
     /**
      * Perform an immediate goto to a point on the map.
      *
-     * Called from {@see CanvasMouseListener}.
+     * Called from {@link CanvasMouseListener}.
      *
      * @param x The x coordinate of the goto destination (pixels).
      * @param y The x coordinate of the goto destination (pixels).
@@ -1754,7 +1755,7 @@ public void changeView(Unit unit) {}
     /**
      * Change to map transform mode, and select a transform.
      *
-     * @param mt The {@code MapTransform} to select.
+     * @param transform The {@code MapTransform} to select.
      */
     public void changeView(MapTransform transform) {}
 
@@ -2108,8 +2109,12 @@ public OptionGroup showGameOptionsDialog(boolean editable) {
 
     /**
      * Show the high scores panel.
+     *
+     * @param messageId The message identifier.
+     * @param scores The {@code HighScore}s to display.
      */
-    public void showHighScoresPanel(String messageId, List<HighScore> scores) {}
+    public void showHighScoresPanel(String messageId,
+                                    List<HighScore> scores) {}
 
     /**
      * Show a panel for a native settlement.
@@ -2160,7 +2165,7 @@ public void showLogFilePanel() {}
     /**
      * Show the main panel.
      *
-     * @parm userMsg An optional user message to display.
+     * @param userMsg An optional user message to display.
      */
     public void showMainPanel(String userMsg) {}
 
@@ -2379,6 +2384,8 @@ public void showReportTradePanel() {}
 
     /**
      * Show the Turn Report.
+     *
+     * @param messages The {@code ModelMessage}s that make up the report.
      */
     public void showReportTurnPanel(List<ModelMessage> messages) {}
 

src/net/sf/freecol/client/gui/ImageLibrary.java

@@ -560,9 +560,9 @@ public static BufferedImage getUnscaledImage(String key) {
      * @param grayscale If true, return the grayscale version of the image.
      * @return The {@code BufferedImage} found by the {@code ResourceManager}.
      */
-    private static BufferedImage getScaledImageInternal(String id, float scale,
+    private static BufferedImage getScaledImageInternal(String key, float scale,
                                                         boolean grayscale) {
-        return ResourceManager.getImage(id, scale, grayscale);
+        return ResourceManager.getImage(key, scale, grayscale);
     }
 
     /**
@@ -573,10 +573,10 @@ private static BufferedImage getScaledImageInternal(String id, float scale,
      * @param grayscale If true, return the grayscale version of the image.
      * @return The {@code BufferedImage} found by the {@code ResourceManager}.
      */
-    private static BufferedImage getSizedImageInternal(String id,
+    private static BufferedImage getSizedImageInternal(String key,
                                                        Dimension size,
                                                        boolean grayscale) {
-        return ResourceManager.getImage(id, size, grayscale);
+        return ResourceManager.getImage(key, size, grayscale);
     }
 
     /**

src/net/sf/freecol/client/gui/MapViewer.java

@@ -781,7 +781,7 @@ int getTileWidth() {
      *
      * @param labelWidth The width of the unit label.
      * @param labelHeight The width of the unit label.
-     * @param tileP The position of the Tile on the screen.
+     * @param tileP The position of the {@code Tile} on the screen.
      * @return The position where to put the label, null if tileP is null.
      */
     public Point calculateUnitLabelPositionInTile(int labelWidth,

src/net/sf/freecol/client/gui/TileViewer.java

@@ -148,7 +148,7 @@ public TileViewer(FreeColClient freeColClient) {
     /**
      * Gets the contained {@code ImageLibrary}.
      *
-     * Public for {@see GUI.getTileImageLibrary}.
+     * Public for {@link GUI#getTileImageLibrary}.
      * 
      * @return The image library;
      */
@@ -188,7 +188,7 @@ public void changeImageLibrary(ImageLibrary lib) {
     /**
      * Returns the scaled terrain-image for a terrain type (and position 0, 0).
      *
-     * Public for {@see GUI.createTileImageWithOverlayAndForest}.
+     * Public for {@link GUI#createTileImageWithOverlayAndForest}.
      *
      * @param type The type of the terrain-image to return.
      * @param size The maximum size of the terrain image to return.
@@ -238,7 +238,7 @@ public BufferedImage createTileImageWithOverlayAndForest(TileType type,
      * Create a {@code BufferedImage} and draw a {@code Tile} on it.
      * Draws the terrain and improvements.
      *
-     * Public for {@see GUI.createTileImageWithBeachBorderAndItems}.
+     * Public for {@link GUI#createTileImageWithBeachBorderAndItems}.
      *
      * @param tile The Tile to draw.
      * @return The image.
@@ -266,7 +266,7 @@ public BufferedImage createTileImageWithBeachBorderAndItems(Tile tile) {
     /**
      * Create a {@code BufferedImage} and draw a {@code Tile} on it.
      *
-     * Public for {@see GUI.createTileImage}.
+     * Public for {@link GUI#createTileImage}.
      *
      * @param tile The {@code Tile} to draw.
      * @param player The {@code Player} to draw for.
@@ -295,7 +295,7 @@ public BufferedImage createTileImage(Tile tile, Player player) {
      * from the corresponding {@code ColonyTile} of the given
      * {@code Colony}.
      *
-     * Public for {@see GUI.createColonyTileImage}.
+     * Public for {@link GUI#createColonyTileImage}.
      *
      * @param tile The {@code Tile} to draw.
      * @param colony The {@code Colony} to create the visualization
@@ -324,7 +324,7 @@ public BufferedImage createColonyTileImage(Tile tile, Colony colony) {
     /**
      * Displays the 3x3 tiles for the TilesPanel in ColonyPanel.
      * 
-     * Public for {@see GUI.displayColonyTles}.
+     * Public for {@link GUI#displayColonyTiles}.
      *
      * @param g The {@code Graphics2D} object on which to draw
      *      the {@code Tile}.

src/net/sf/freecol/client/gui/dialog/GameOptionsDialog.java

@@ -30,7 +30,7 @@
 
 
 /**
- * Dialog for changing the {@link net.sf.freecol.common.model.GameOptions}.
+ * Dialog for changing the {@link net.sf.freecol.common.option.GameOptions}.
  */
 public final class GameOptionsDialog extends OptionsDialog {
 

src/net/sf/freecol/client/gui/dialog/SelectAmountDialog.java

@@ -127,6 +127,7 @@ public boolean verify(JComponent input) {
     /**
      * Verify the contents of the JComboBox.
      *
+     * @param box The {@code JComboBox} to verify.
      * @return True if all is well.
      */
     private boolean verifyWholeBox(JComboBox<Integer> box) {

src/net/sf/freecol/client/gui/panel/InfoPanel.java

@@ -77,13 +77,14 @@ public final class InfoPanel extends FreeColPanel {
 
     private static final int SLACK = 5; // Small gap
 
-    /**
-     * Panel for ending the turn.
-     *
-     * @param freeColClient The {@code FreeColClient} for the game.
-     */
+    /** Panel for ending the turn. */
     private static class EndTurnPanel extends FreeColPanel {
 
+        /**
+         * Build a new end panel.
+         *
+         * @param freeColClient The {@code FreeColClient} for the game.
+         */
         public EndTurnPanel(FreeColClient freeColClient) {
             super(freeColClient, null,
                   new MigLayout("wrap 1, center", "[center]", ""));

src/net/sf/freecol/client/gui/panel/Utility.java

@@ -641,7 +641,6 @@ public static void localizeToolTip(JComponent comp, String key) {
      *
      * @param comp The {@code JComponent} to localize.
      * @param template The {@code StringTemplate} to use.
-     * @return The original {@code JComponent}.
      */
     public static void localizeToolTip(JComponent comp,
                                        StringTemplate template) {

src/net/sf/freecol/client/networking/UserServerAPI.java

@@ -111,7 +111,11 @@ private synchronized void updateConnection(Connection c) {
     /**
      * Create a new connection.
      *
+     * @param name The name to associate with the connection.
+     * @param host The name of the host to connect to.
+     * @param port The port to connect to.
      * @return The new <code>Connection</code>.
+     * @exception IOException on failure to connect.
      */
     private static Connection newConnection(String name, String host, int port)
         throws IOException {