Javadoc warnings cleanups.

Note: this involves generated code from a samskivert patch I only just sent to mdb,
but he's in a meeting, so that won't show up for a little.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@5369 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/admin/client/AdminService.java

@@ -30,13 +30,12 @@ import com.threerings.presents.client.InvocationService;
 public interface AdminService extends InvocationService
 {
     /**
-     * Used to communicate a response to a {@link #getConfigInfo} request.
+     * Used to communicate a response to a {@link AdminService#getConfigInfo} request.
      */
     public static interface ConfigInfoListener extends InvocationListener
     {
         /**
-         * Delivers a successful response to a {@link #getConfigInfo}
+         * Delivers a successful response to a {@link AdminService#getConfigInfo} request.
-         * request.
          */
         void gotConfigInfo (String[] keys, int[] oids);
     }

src/java/com/threerings/admin/server/persist/ConfigRecord.java

@@ -100,7 +100,7 @@ public class ConfigRecord extends PersistentRecord
 
     // AUTO-GENERATED: METHODS START
     /**
-     * Create and return a primary {@link Key} to identify a {@link #ConfigRecord}
+     * Create and return a primary {@link Key} to identify a {@link ConfigRecord}
      * with the supplied key values.
      */
     public static Key<ConfigRecord> getKey (String node, String object, String field)

src/java/com/threerings/bureau/server/BureauRegistry.java

@@ -59,7 +59,7 @@ public class BureauRegistry
     /**
      * Defines how a bureau is launched. Instances are associated to bureau types by the server on
      * startup. The instances are used whenever the registry needs to launch a bureau for an agent
-     * with the assocated bureau type.
+     * with the associated bureau type.
      */
     public static interface Launcher
     {
@@ -75,7 +75,7 @@ public class BureauRegistry
 
     /**
      * Defines how to generate a command to launch a bureau in a local process.
-     * @see #setCommandGenerator
+     * @see #setCommandGenerator(String,CommandGenerator,int)
      * @see Launcher
      */
     public static interface CommandGenerator
@@ -172,9 +172,7 @@ public class BureauRegistry
      * @param bureauType the type of bureau that will be launched
      * @param cmdGenerator the generator to be used for bureaus of <code>bureauType</code>
      */
-    public void setCommandGenerator (
+    public void setCommandGenerator (String bureauType, final CommandGenerator cmdGenerator)
-        String bureauType,
-        final CommandGenerator cmdGenerator)
     {
         setCommandGenerator(bureauType, cmdGenerator, 0);
     }
@@ -190,9 +188,7 @@ public class BureauRegistry
      * @param timeout milliseconds to wait for the bureau or 0 to wait forever
      */
     public void setCommandGenerator (
-        String bureauType,
+        String bureauType, final CommandGenerator cmdGenerator, int timeout)
-        final CommandGenerator cmdGenerator,
-        int timeout)
     {
         setLauncher(bureauType, new Launcher() {
             public void launchBureau (String bureauId, String token)

src/java/com/threerings/crowd/chat/client/ChatDirector.java

@@ -864,7 +864,7 @@ public class ChatDirector extends BasicDirector
         return buf.toString();
     }
 
-    /** Helper function for {@link #mogrifyChat}. */
+    /** Helper function for {@link #mogrifyChat(String,boolean,boolean)}. */
     protected StringBuffer mogrifyChat (
         StringBuffer buf, boolean transformsAllowed, boolean capFirst)
     {
@@ -1152,9 +1152,9 @@ public class ChatDirector extends BasicDirector
                 Object[] commands = possibleCommands.keySet().toArray();
                 Arrays.sort(commands);
                 String commandList = "";
-                for (int ii = 0; ii < commands.length; ii++) {
+                for (Object element : commands) {
-                    commandList += " /" + commands[ii];
+                        commandList += " /" + element;
-                }
+                    }
                 return MessageBundle.tcompose("m.usage_help", commandList);
             }
         }

src/java/com/threerings/crowd/chat/client/ChatService.java

@@ -36,17 +36,16 @@ import com.threerings.presents.client.InvocationService;
 public interface ChatService extends InvocationService
 {
     /**
-     * Used to communicate the response to a {@link #tell} request.
+     * Used to communicate the response to a {@link ChatService#tell} request.
      */
     public static interface TellListener extends InvocationListener
     {
         /**
-         * Communicates the response to a {@link #tell} request.
+         * Communicates the response to a {@link ChatService#tell} request.
          *
-         * @param idleTime the number of ms the tellee has been idle or 0L
+         * @param idleTime the number of ms the tellee has been idle or 0L if they are not idle.
-         * if they are not idle.
+         * @param awayMessage the away message configured by the told player or null if they have
-         * @param awayMessage the away message configured by the told
+         * no away message.
-         * player or null if they have no away message.
          */
         void tellSucceeded (long idleTime, String awayMessage);
     }
@@ -56,8 +55,7 @@ public interface ChatService extends InvocationService
      * equal to <code>target</code>.
      *
      * @param client a connected, operational client instance.
-     * @param target the username of the user to which the tell message
+     * @param target the username of the user to which the tell message should be delivered.
-     * should be delivered.
      * @param message the contents of the message.
      * @param listener the reference that will receive the tell response.
      */

src/java/com/threerings/crowd/chat/data/SpeakObject.java

@@ -29,7 +29,7 @@ import com.threerings.util.Name;
  */
 public interface SpeakObject
 {
-    /** Used in conjunction with {@link #applyToListeners}. */
+    /** Used in conjunction with {@link SpeakObject#applyToListeners}. */
     public static interface ListenerOp
     {
         /** Call this method if you only have access to body oids. */

src/java/com/threerings/crowd/client/LocationService.java

@@ -34,12 +34,12 @@ import com.threerings.crowd.data.PlaceConfig;
 public interface LocationService extends InvocationService
 {
     /**
-     * Used to communicate responses to {@link #moveTo} requests.
+     * Used to communicate responses to {@link LocationService#moveTo} requests.
      */
     public static interface MoveListener extends InvocationListener
     {
         /**
-         * Called in response to a successful {@link #moveTo} request.
+         * Called in response to a successful {@link LocationService#moveTo} request.
          */
         void moveSucceeded (PlaceConfig config);
     }

src/java/com/threerings/crowd/server/BodyManager.java

@@ -41,7 +41,7 @@ import static com.threerings.crowd.Log.log;
 public class BodyManager
     implements BodyProvider
 {
-    /** Used by {@link #updateOccupantInfo}. */
+    /** Used by {@link BodyManager#updateOccupantInfo}. */
     public static interface OccupantInfoOp
     {
         /**

src/java/com/threerings/crowd/server/PlaceRegistry.java

@@ -50,7 +50,7 @@ import static com.threerings.crowd.Log.log;
 public class PlaceRegistry
     implements ShutdownManager.Shutdowner
 {
-    /** Used in conjunction with {@link #createPlace}. */
+    /** Used in conjunction with {@link PlaceRegistry#createPlace(PlaceConfig,PreStartupHook)}. */
     public static interface PreStartupHook
     {
         void invoke (PlaceManager plmgr);

src/java/com/threerings/io/ObjectInputStream.java

@@ -182,7 +182,7 @@ public class ObjectInputStream extends DataInputStream
 
     /**
      * Reads an object from the input stream that was previously written with {@link
-     * ObjectOutputStream#writeBareObject}.
+     * ObjectOutputStream#writeBareObject(Object)}.
      *
      * @param object the object to be populated from data on the stream.  It cannot be
      * <code>null</code>.
@@ -195,7 +195,7 @@ public class ObjectInputStream extends DataInputStream
 
     /**
      * Reads an object from the input stream that was previously written with {@link
-     * ObjectOutputStream#writeBareObject}.
+     * ObjectOutputStream#writeBareObject(Object,Streamer,boolean)}.
      */
     protected void readBareObject (Object object, Streamer streamer, boolean useReader)
         throws IOException, ClassNotFoundException

src/java/com/threerings/io/ObjectOutputStream.java

@@ -154,7 +154,7 @@ public class ObjectOutputStream extends DataOutputStream
      * Writes a {@link Streamable} instance or one of the support object types <em>without
      * associated class metadata</em> to the output stream. The caller is responsible for knowing
      * the exact class of the written object, creating an instance of such and calling {@link
-     * ObjectInputStream#readBareObject} to read its data from the stream.
+     * ObjectInputStream#readBareObject(Object)} to read its data from the stream.
      *
      * @param object the object to be written. It cannot be <code>null</code>.
      */

src/java/com/threerings/io/SimpleStreamableObject.java

@@ -26,7 +26,7 @@ import com.threerings.util.ActionScript;
 
 /**
  * A simple serializable object implements the {@link Streamable}
- * interface and provides a default {@link #toString} implementation which
+ * interface and provides a default {@link Object#toString} implementation which
  * outputs all public members.
  */
 public class SimpleStreamableObject implements Streamable

src/java/com/threerings/io/TrackedStreamableObject.java

@@ -27,7 +27,7 @@ import com.threerings.util.TrackedObject;
 
 /**
  * A simple serializable object implements the {@link Streamable}
- * interface and provides a default {@link #toString} implementation which
+ * interface and provides a default {@link Object#toString} implementation which
  * outputs all public members.
  */
 public class TrackedStreamableObject extends TrackedObject

src/java/com/threerings/presents/client/Client.java

@@ -21,6 +21,8 @@
 
 package com.threerings.presents.client;
 
+import static com.threerings.presents.Log.log;
+
 import java.util.HashSet;
 
 import com.samskivert.util.Interval;
@@ -28,7 +30,7 @@ import com.samskivert.util.ObserverList;
 import com.samskivert.util.RunAnywhere;
 import com.samskivert.util.RunQueue;
 import com.samskivert.util.StringUtil;
-
+import com.threerings.presents.client.InvocationService.ConfirmListener;
 import com.threerings.presents.data.AuthCodes;
 import com.threerings.presents.data.ClientObject;
 import com.threerings.presents.data.InvocationCodes;
@@ -41,8 +43,6 @@ import com.threerings.presents.net.Credentials;
 import com.threerings.presents.net.PingRequest;
 import com.threerings.presents.net.PongResponse;
 
-import static com.threerings.presents.Log.log;
-
 /**
  * Through the client object, a connection to the system is established and maintained. The client
  * object maintains two separate threads (a reader and a writer) by which all network traffic is
@@ -117,7 +117,7 @@ public class Client
      * ports (which will be tried in succession).
      *
      * @see #logon
-     * @see #moveToServer
+     * @see #moveToServer(String,int[],ConfirmListener)
      */
     public void setServer (String hostname, int[] ports)
     {
@@ -129,7 +129,7 @@ public class Client
      * ports (which will be tried in succession), and datagram ports.
      *
      * @see #logon
-     * @see #moveToServer
+     * @see #moveToServer(String,int[],ConfirmListener)
      */
     public void setServer (String hostname, int[] ports, int[] datagramPorts)
     {
@@ -894,7 +894,8 @@ public class Client
         protected boolean _rejected;
     }
 
-    /** Handles the process of switching between servers. See {@link #moveToServer}. */
+    /** Handles the process of switching between servers.
+     * See {@link Client#moveToServer(String,int[],int[],ConfirmListener)}. */
     protected class ServerSwitcher extends ClientAdapter
     {
         public ServerSwitcher (

src/java/com/threerings/presents/client/ClientObserver.java

@@ -25,10 +25,10 @@ package com.threerings.presents.client;
  * A client observer is a more detailed version of the {@link SessionObserver} for entities that
  * are interested in more detail about the logon/logoff process.
  *
- * <p> In the normal course of affairs, {@link #clientDidLogon} will be called after the client
+ * <p> In the normal course of affairs, {@link SessionObserver#clientDidLogon} will be called after
- * successfully logs on to the server and {@link #clientDidLogoff} will be called after the client
+ * the client successfully logs on to the server and {@link SessionObserver#clientDidLogoff} will
- * logs off of the server. If logon fails for any reson, {@link #clientFailedToLogon} will be
+ * be called after the client logs off of the server. If logon fails for any reason,
- * called to explain the failure.
+ * {@link #clientFailedToLogon} will be called to explain the failure.
  *
  * <p> {@link #clientWillLogoff} will only be called when an abortable logoff is requested (like
  * when the user clicks on a logoff button of some sort). It will not be called during
@@ -38,8 +38,9 @@ package com.threerings.presents.client;
  * calls {@link #clientWillLogoff}</em>).
  *
  * <p> If the client connection fails unexpectedly, {@link #clientConnectionFailed} will be called
- * to let the observers know that we lost our connection to the server. {@link #clientDidLogoff}
+ * to let the observers know that we lost our connection to the server.
- * will be called immediately afterwards as a normal logoff procedure is effected.
+ * {@link SessionObserver#clientDidLogoff} will be called immediately afterwards as a normal logoff
+ * procedure is effected.
  */
 public interface ClientObserver extends SessionObserver
 {
@@ -58,7 +59,7 @@ public interface ClientObserver extends SessionObserver
 
     /**
      * Called when the connection to the server went away for some unexpected reason. This will be
-     * followed by a call to {@link #clientDidLogoff}.
+     * followed by a call to {@link SessionObserver#clientDidLogoff}.
      */
     void clientConnectionFailed (Client client, Exception cause);
 

src/java/com/threerings/presents/client/TimeBaseService.java

@@ -28,12 +28,12 @@ package com.threerings.presents.client;
 public interface TimeBaseService extends InvocationService
 {
     /**
-     * Used to communicated the result of a {@link #getTimeOid} request.
+     * Used to communicated the result of a {@link TimeBaseService#getTimeOid} request.
      */
     public static interface GotTimeBaseListener extends InvocationListener
     {
         /**
-         * Communicates the result of a successful {@link #getTimeOid} request.
+         * Communicates the result of a successful {@link TimeBaseService#getTimeOid} request.
          */
         void gotTimeOid (int timeOid);
     }

src/java/com/threerings/presents/data/ClientObject.java

@@ -82,8 +82,8 @@ public class ClientObject extends DObject
     }
 
     /**
-     * Convenience wrapper around {@link #checkAccess} that simply returns a boolean indicating
+     * Convenience wrapper around {@link #checkAccess(Permission,Object)} that simply returns a
-     * whether or not this client has the permission rather than an explanation.
+     * boolean indicating whether or not this client has the permission rather than an explanation.
      */
     public boolean hasAccess (Permission perm, Object context)
     {
@@ -91,8 +91,8 @@ public class ClientObject extends DObject
     }
 
     /**
-     * Convenience wrapper around {@link #checkAccess} that simply returns a boolean indicating
+     * Convenience wrapper around {@link #checkAccess(Permission)} that simply returns a boolean
-     * whether or not this client has the permission rather than an explanation.
+     * indicating whether or not this client has the permission rather than an explanation.
      */
     public boolean hasAccess (Permission perm)
     {

src/java/com/threerings/presents/data/Permission.java

@@ -22,7 +22,8 @@
 package com.threerings.presents.data;
 
 /**
- * A value class used by {@link ClientObject#checkAccess} to do fine-grained access control.
+ * A value class used by {@link ClientObject#checkAccess(Permission)} to do fine-grained access
+ * control.
  */
 public class Permission
 {

src/java/com/threerings/presents/peer/server/PeerManager.java

@@ -108,7 +108,7 @@ public abstract class PeerManager
 
     /**
      * Wraps an operation that needs a shared resource lock to be acquired before it can be
-     * performed, and released after it completes. Used by {@link #performWithLock}.
+     * performed, and released after it completes. Used by {@link PeerManager#performWithLock}.
      */
     public static interface LockedOperation
     {

src/java/com/threerings/presents/peer/server/persist/NodeRecord.java

@@ -127,7 +127,7 @@ public class NodeRecord extends PersistentRecord
 
     // AUTO-GENERATED: METHODS START
     /**
-     * Create and return a primary {@link Key} to identify a {@link #NodeRecord}
+     * Create and return a primary {@link Key} to identify a {@link NodeRecord}
      * with the supplied key values.
      */
     public static Key<NodeRecord> getKey (String nodeName)

src/java/com/threerings/presents/server/ClientManager.java

@@ -64,7 +64,7 @@ public class ClientManager
                ReportManager.Reporter, ShutdownManager.Shutdowner
 {
     /**
-     * Used by {@link #applyToClient}.
+     * Used by {@link ClientManager#applyToClient}.
      */
     public static interface ClientOp
     {
@@ -519,7 +519,7 @@ public class ClientManager
         }
     }
 
-    /** Used by {@link #applyToClient}. */
+    /** Used by {@link ClientManager#applyToClient}. */
     protected class ClientOpResolver
         implements ClientResolutionListener
     {

src/java/com/threerings/presents/server/InvocationException.java

@@ -46,7 +46,7 @@ public class InvocationException extends Exception
     }
 
     /**
-     * A version of {@link #requireAccess} that takes no context.
+     * A version of {@link #requireAccess(ClientObject,Permission,Object)} that takes no context.
      */
     public static void requireAccess (ClientObject clobj, Permission perm)
         throws InvocationException
@@ -55,8 +55,7 @@ public class InvocationException extends Exception
     }
 
     /**
-     * Constructs an invocation exception with the supplied cause code
+     * Constructs an invocation exception with the supplied cause code string.
-     * string.
      */
     public InvocationException (String cause)
     {
@@ -66,8 +65,7 @@ public class InvocationException extends Exception
     /**
      * Constructs an invocation exception with the supplied cause code
      * string and qualifying message bundle. The error code will be
-     * qualified with the message bundle (see {@link
+     * qualified with the message bundle (see {@link MessageBundle#qualify}).
-     * MessageBundle#qualify}).
      */
     public InvocationException (String bundle, String code)
     {

src/java/com/threerings/presents/server/PresentsClient.java

@@ -82,7 +82,7 @@ import static com.threerings.presents.Log.log;
 public class PresentsClient
     implements MessageHandler, ClientResolutionListener
 {
-    /** Used by {@link #setUsername} to report success or failure. */
+    /** Used by {@link PresentsClient#setUsername} to report success or failure. */
     public static interface UserChangeListener
     {
         /** Called when the new client object has been resolved and the new client object reported

src/java/com/threerings/presents/server/ReportManager.java

@@ -38,7 +38,10 @@ import static com.threerings.presents.Log.log;
 @Singleton
 public class ReportManager
 {
-    /** Used to generate "state of the server" reports. See {@link #registerReporter}. */
+    /**
+     * Used to generate "state of the server" reports.
+     * See {@link ReportManager#registerReporter}.
+     * */
     public static interface Reporter
     {
         /**
@@ -155,7 +158,7 @@ public class ReportManager
     /** The time at which the server was started. */
     protected long _serverStartTime = System.currentTimeMillis();
 
-    /** The last time at which {@link #generateReport} was run. */
+    /** The last time at which {@link #generateReport(long,boolean)} was run. */
     protected long _lastReportStamp = _serverStartTime;
 
     /** Used to generate "state of server" reports. */

src/java/com/threerings/presents/server/ShutdownManager.java

@@ -47,7 +47,7 @@ public class ShutdownManager
         void shutdown ();
     }
 
-    /** Constraints for use with {@link #addConstraint}. */
+    /** Constraints for use with {@link ShutdownManager#addConstraint}. */
     public static enum Constraint { RUNS_BEFORE, RUNS_AFTER };
 
     @Inject ShutdownManager (@EventQueue RunQueue dobjq)

src/java/com/threerings/presents/server/net/ConnectionManager.java

@@ -284,21 +284,20 @@ public class ConnectionManager extends LoopingThread
     {
         int successes = 0;
         IOException failure = null;
-        for (int ii = 0; ii < _ports.length; ii++) {
+        for (int port : _ports) {
             try {
                 // create a listening socket and add it to the select set
                 _ssocket = ServerSocketChannel.open();
                 _ssocket.configureBlocking(false);
 
-                InetSocketAddress isa = new InetSocketAddress(_ports[ii]);
+                InetSocketAddress isa = new InetSocketAddress(port);
                 _ssocket.socket().bind(isa);
                 registerChannel(_ssocket);
                 successes++;
                 log.info("Server listening on " + isa + ".");
 
             } catch (IOException ioe) {
-                log.warning("Failure listening to socket on port '" +
+                log.warning("Failure listening to socket on port '" + port + "'.", ioe);
-                        _ports[ii] + "'.", ioe);
                 failure = ioe;
             }
         }
@@ -940,7 +939,7 @@ public class ConnectionManager extends LoopingThread
         notifyObservers(CONNECTION_CLOSED, conn, null, null);
     }
 
-    /** Used to handle partial writes in {@link #writeMessage}. */
+    /** Used to handle partial writes in {@link ConnectionManager#writeMessage}. */
     protected static interface PartialWriteHandler
     {
         void handlePartialWrite (Connection conn, ByteBuffer buffer);

tests/src/java/com/threerings/presents/client/TestService.java

@@ -28,19 +28,18 @@ import java.util.ArrayList;
  */
 public interface TestService extends InvocationService
 {
-    /** Used to dispatch responses to {@link #test} requests. */
+    /** Used to dispatch responses to {@link TestService#test} requests. */
     public static interface TestFuncListener extends InvocationListener
     {
-        /** Informs listener of successful {@link #test} request. */
+        /** Informs listener of successful {@link TestService#test} request. */
         public void testSucceeded (String one, int two);
     }
 
     /** Issues a test request. */
     public void test (
-        Client client, String one, int two, ArrayList<Integer> three,
+        Client client, String one, int two, ArrayList<Integer> three, TestFuncListener listener);
-        TestFuncListener listener);
 
-    /** Used to dispatch responses to {@link #getTestOid} requests. */
+    /** Used to dispatch responses to {@link TestService#getTestOid} requests. */
     public static interface TestOidListener extends InvocationListener
     {
         /** Communicates test oid to listener. */