A variety of javadoc fixes.

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

build.xml

@@ -82,7 +82,7 @@
       <link href="http://java.sun.com/j2se/1.5/docs/api/"/>
       <!-- ant documentation is not available online, sorry kids -->
       <link href="file:///usr/share/doc/ant-doc/javadocs"/>
-      <link href="http://samskivert.com/code/samskivert/samskivert/docs/api"/>
+      <link href="http://samskivert.googlecode.com/svn/apidocs"/>
     </javadoc>
   </target>
 

src/main/java/com/threerings/admin/data/AdminMarshaller.java

@@ -40,7 +40,7 @@ public class AdminMarshaller extends InvocationMarshaller
     implements AdminService
 {
     /**
-     * Marshalls results to implementations of {@link AdminService.ConfigInfoListener}.
+     * Marshalls results to implementations of {@code AdminService.ConfigInfoListener}.
      */
     public static class ConfigInfoMarshaller extends ListenerMarshaller
         implements ConfigInfoListener

src/main/java/com/threerings/admin/web/gwt/ConfigServiceAsync.java

@@ -27,17 +27,17 @@ import com.threerings.admin.web.gwt.ConfigService.ConfigurationRecord;
 import com.threerings.admin.web.gwt.ConfigService.ConfigurationResult;
 
 /**
- * Provides the asynchronous version of {@link com.threerings.admin.web.gwt.AdminService}.
+ * Provides the asynchronous version of {@link ConfigService}.
  */
 public interface ConfigServiceAsync
 {
     /**
-     * The async version of {@link com.threerings.admin.web.gwt.ConfigService#getConfig}.
+     * The async version of {@link ConfigService#getConfiguration}.
      */
     public void getConfiguration (AsyncCallback<ConfigurationResult> callback);
 
     /**
-     * The async version of {@link com.threerings.admin.web.gwt.ConfigService#updateConfiguration}.
+     * The async version of {@link ConfigService#updateConfiguration}.
      */
     public void updateConfiguration (
         String key, ConfigField[] updates, AsyncCallback<ConfigurationRecord> callback);

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

@@ -148,7 +148,6 @@ public class ChatDirector extends BasicDirector
      * register itself as a location observer so that it can automatically process place
      * constrained chat.
      *
-     * @param msgmgr the message manager via which we do our translations.
      * @param bundle the message bundle from which we obtain our chat-related translation strings.
      */
     public ChatDirector (CrowdContext ctx, String bundle)
@@ -894,7 +893,7 @@ public class ChatDirector extends BasicDirector
         return buf.toString();
     }
 
-    /** Helper function for {@link #mogrifyChat(String,boolean,boolean)}. */
+    /** Helper function for {@link #mogrifyChat(String,byte,boolean,boolean)}. */
     protected StringBuffer mogrifyChat (
         StringBuffer buf, boolean transformsAllowed, boolean capFirst)
     {

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

@@ -52,7 +52,6 @@ public interface ChatService extends InvocationService
      * Requests that a tell message be delivered to the user with username equal to
      * <code>target</code>.
      *
-     * @param client a connected, operational client instance.
      * @param target the username of the user to which the tell message should be delivered.
      * @param message the contents of the message.
      * @param listener the reference that will receive the tell response.
@@ -62,7 +61,6 @@ public interface ChatService extends InvocationService
     /**
      * Requests that a message be broadcast to all users in the system.
      *
-     * @param client a connected, operational client instance.
      * @param message the contents of the message.
      * @param listener the reference that will receive a failure response.
      */

src/main/java/com/threerings/crowd/chat/data/ChatMarshaller.java

@@ -42,7 +42,7 @@ public class ChatMarshaller extends InvocationMarshaller
     implements ChatService
 {
     /**
-     * Marshalls results to implementations of {@link ChatService.TellListener}.
+     * Marshalls results to implementations of {@code ChatService.TellListener}.
      */
     public static class TellMarshaller extends ListenerMarshaller
         implements TellListener

src/main/java/com/threerings/crowd/chat/server/ChatHistory.java

@@ -155,7 +155,7 @@ public class ChatHistory
     }
 
     /**
-     * Causes the chat history for the given user to be held briefly after the {@link #clear()}
+     * Causes the chat history for the given user to be held briefly after the {@link #clear}
      * call so that session observers can grab it.
      */
     public void hold (Name username)

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

@@ -46,8 +46,6 @@ public interface LocationService extends InvocationService
     /**
      * Requests that this client's body be moved to the specified location.
      *
-     * @param client a reference to the client object that defines the context in which this
-     * invocation service should be executed.
      * @param placeId the object id of the place object to which the body should be moved.
      * @param listener the listener that will be informed of success or failure.
      */

src/main/java/com/threerings/crowd/data/BodyObject.java

@@ -132,7 +132,7 @@ public class BodyObject extends ClientObject
 
     /**
      * Return the {@link ClientObject} that represent our driving user's connection. This is
-     * the reverse operation of {@link BodyLocator#forClient} and should match it. The default
+     * the reverse operation of {@code BodyLocator.forClient} and should match it. The default
      * implementation assumes the client object and the body object are one and the same.
      *
      * Do not return null here once this object is in the wild.

src/main/java/com/threerings/crowd/data/LocationMarshaller.java

@@ -40,7 +40,7 @@ public class LocationMarshaller extends InvocationMarshaller
     implements LocationService
 {
     /**
-     * Marshalls results to implementations of {@link LocationService.MoveListener}.
+     * Marshalls results to implementations of {@code LocationService.MoveListener}.
      */
     public static class MoveMarshaller extends ListenerMarshaller
         implements MoveListener

src/main/java/com/threerings/crowd/data/TokenRing.java

@@ -26,7 +26,7 @@ import com.threerings.io.SimpleStreamableObject;
 /**
  * Defines access control tokens that convey certain privileges to users.
  *
- * @see BodyObject#CrowdPermissionPolicy
+ * @see BodyObject.CrowdPermissionPolicy
  */
 public class TokenRing extends SimpleStreamableObject
 {

src/main/java/com/threerings/crowd/server/CrowdObjectAccess.java

@@ -66,7 +66,8 @@ public class CrowdObjectAccess
     };
 
     /**
-     * Extends the access control in {@link #PLACE} to allow Bureau clients to subscribe.
+     * Extends the access control in {@link PlaceAccessController} to allow Bureau clients to
+     * subscribe.
      */
     @Singleton
     public static class BureauAccessController extends PlaceAccessController

src/main/java/com/threerings/crowd/server/PlaceManager.java

@@ -510,7 +510,7 @@ public class PlaceManager
 
     /**
      * Creates an access controller for this place's distributed object, which by default is {@link
-     * CrowdObjectAccess#PLACE}.
+     * PlaceAccessController}.
      */
     protected AccessController getAccessController ()
     {
@@ -639,7 +639,7 @@ public class PlaceManager
      * Adds this occupant's info to the {@link PlaceObject}. This is called in a transaction on the
      * place object so if a derived class needs to add additional information for an occupant it
      * should override this method. It may opt to add the information before calling super if it
-     * wishes to rely on its information being configured when {@link #bodyAdded} is called.
+     * wishes to rely on its information being configured when {@link #bodyEntered} is called.
      */
     protected void addOccupantInfo (BodyObject body, OccupantInfo info)
     {

src/main/java/com/threerings/nio/conman/Connection.java

@@ -34,7 +34,6 @@ import java.nio.channels.SocketChannel;
  */
 public abstract class Connection implements NetEventHandler
 {
-
     /** The key used by the NIO code to track this connection. */
     public SelectionKey selkey;
 

src/main/java/com/threerings/nio/conman/ServerSocketChannelAcceptor.java

@@ -45,8 +45,8 @@ public class ServerSocketChannelAcceptor
 {
     /**
      * Configures the connection manager with the hostname and ports on which it will listen for
-     * socket connections. This must be called before the connection manager is started (via
+     * socket connections. This must be called before the connection manager is started as the
-     * {@via #start}) as the sockets will be bound at that time.
+     * sockets will be bound at that time.
      *
      * @param socketHostname the hostname to which we bind our sockets or null to bind to all
      * interfaces.

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

@@ -128,7 +128,7 @@ public class Client
      * ports (which will be tried in succession).
      *
      * @see #logon
-     * @see #moveToServer(String,int[],ConfirmListener)
+     * @see #moveToServer
      */
     public void setServer (String hostname, int[] ports)
     {
@@ -140,7 +140,7 @@ public class Client
      * ports (which will be tried in succession), and datagram ports.
      *
      * @see #logon
-     * @see #moveToServer(String,int[],ConfirmListener)
+     * @see #moveToServer
      */
     public void setServer (String hostname, int[] ports, int[] datagramPorts)
     {
@@ -969,8 +969,7 @@ public class Client
         return false;
     }
 
-    /** Handles the process of switching between servers.
+    /** Handles the process of switching between servers. See {@link Client#moveToServer}. */
-     * See {@link Client#moveToServer(String,int[],int[],ConfirmListener)}. */
     protected class ServerSwitcher extends ClientAdapter
     {
         public ServerSwitcher (

src/main/java/com/threerings/presents/data/InvocationMarshaller.java

@@ -148,7 +148,7 @@ public class InvocationMarshaller
     }
 
     /**
-     * Defines a marshaller for the standard {@link InvocationService.ConfirmListener}.
+     * Defines a marshaller for the standard {@code InvocationService.ConfirmListener}.
      */
     public static class ConfirmMarshaller extends ListenerMarshaller
         implements ConfirmListener
@@ -179,7 +179,7 @@ public class InvocationMarshaller
     }
 
     /**
-     * Defines a marshaller for the standard {@link InvocationService.ResultListener}.
+     * Defines a marshaller for the standard {@code InvocationService.ResultListener}.
      */
     public static class ResultMarshaller extends ListenerMarshaller
         implements ResultListener

src/main/java/com/threerings/presents/data/TimeBaseMarshaller.java

@@ -39,7 +39,7 @@ public class TimeBaseMarshaller extends InvocationMarshaller
     implements TimeBaseService
 {
     /**
-     * Marshalls results to implementations of {@link TimeBaseService.GotTimeBaseListener}.
+     * Marshalls results to implementations of {@code TimeBaseService.GotTimeBaseListener}.
      */
     public static class GotTimeBaseMarshaller extends ListenerMarshaller
         implements GotTimeBaseListener

src/main/java/com/threerings/presents/dobj/DSet.java

@@ -277,7 +277,7 @@ public class DSet<E extends DSet.Entry>
      * the <code>array</code> argument is null, an object array of sufficient size to contain all
      * of the elements of this set will be created and returned.
      *
-     * @deprecated use {@link #clone} or add this to an {@link ArrayList}. Arrays are an untypesafe
+     * @deprecated use {@link #clone} or add this to an ArrayList. Arrays are an untypesafe
      * quagmire.
      */
     @Deprecated
@@ -292,7 +292,7 @@ public class DSet<E extends DSet.Entry>
     }
 
     /**
-     * @deprecated use {@link #clone} or add this to an {@link ArrayList}. Arrays are an untypesafe
+     * @deprecated use {@link #clone} or add this to an ArrayList. Arrays are an untypesafe
      * quagmire.
      */
     @Deprecated

src/main/java/com/threerings/presents/dobj/EntryEvent.java

@@ -29,7 +29,10 @@ import com.threerings.presents.net.Transport;
 public abstract class EntryEvent<T extends DSet.Entry> extends NamedEvent
 {
     /**
-     * {@inheritDoc}
+     * Constructs a new event for the specified target object with the supplied attribute name.
+     *
+     * @param targetOid the object id of the object in question.
+     * @param name the name associated with this event.
      */
     public EntryEvent (int targetOid, String name)
     {
@@ -37,7 +40,11 @@ public abstract class EntryEvent<T extends DSet.Entry> extends NamedEvent
     }
 
     /**
-     * {@inheritDoc}
+     * Constructs a new event for the specified target object with the supplied attribute name.
+     *
+     * @param targetOid the object id of the object in question.
+     * @param name the name associated with this event.
+     * @param transport a hint as to the type of transport desired for the event.
      */
     public EntryEvent (int targetOid, String name, Transport transport)
     {

src/main/java/com/threerings/presents/server/InvocationManager.java

@@ -245,9 +245,9 @@ public class InvocationManager
     }
 
     /**
-     * @Deprecated use {@link #registerDispatcher(InvocationDispatcher)}.
+     * @deprecated use {@link #registerDispatcher(InvocationDispatcher)}.
      */
-    public <T extends InvocationMarshaller> T registerDispatcher (
+    @Deprecated public <T extends InvocationMarshaller> T registerDispatcher (
         InvocationDispatcher<T> dispatcher, boolean bootstrap)
     {
         return registerDispatcher(dispatcher, null);

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

@@ -29,9 +29,9 @@ import com.samskivert.util.Lifecycle;
 /**
  * Handles the orderly shutdown of all server services.
  *
- * @Deprecated use Lifecycle
+ * @deprecated use Lifecycle
  */
-@Singleton
+@Deprecated @Singleton
 public class ShutdownManager
 {
     /** Implementers of this interface will be notified when the server is shutting down. */

src/main/java/com/threerings/presents/server/net/PresentsConnection.java

@@ -50,7 +50,7 @@ import static com.threerings.presents.Log.log;
  */
 public class PresentsConnection extends Connection
 {
-    /** Used with {@link Connection#setMessageHandler}. */
+    /** Used with {@link #setMessageHandler}. */
     public static interface MessageHandler {
         /** Called when a complete message has been parsed from incoming network data. */
         void handleMessage (Message message);

src/main/java/com/threerings/presents/util/InvocationAdapter.java

@@ -27,7 +27,7 @@ import com.threerings.presents.client.InvocationService;
 import com.threerings.presents.server.InvocationException;
 
 /**
- * Adapts the response from a {@link InvocationService.ResultListener} to a {@link ResultListener}.
+ * Adapts the response from a {@code InvocationService.ResultListener} to a {@link ResultListener}.
  * In the event of failure, the failure string is wrapped in an {@link InvocationException}.
  */
 public class InvocationAdapter implements InvocationService.ResultListener

src/main/java/com/threerings/presents/util/PersistingUnit.java

@@ -32,7 +32,7 @@ import static com.threerings.presents.Log.log;
 
 /**
  * Simplifies a common pattern which is to post an {@link Invoker} unit which does some database
- * operation and then calls back to an {@link InvocationService.InvocationListener} of some
+ * operation and then calls back to an {@code InvocationService.InvocationListener} of some
  * sort. If the database operation fails, the error will be logged and the result listener will be
  * replied to with {@link InvocationCodes#INTERNAL_ERROR}.
  */

src/main/resources/com/threerings/presents/tools/marshaller.tmpl

@@ -19,7 +19,7 @@ public class {{name}}Marshaller extends InvocationMarshaller
 {
 {{#listeners}}
     /**
-     * Marshalls results to implementations of {@code {{name}}Service#{{listenerName}}Listener}.
+     * Marshalls results to implementations of {@code {{name}}Service.{{listenerName}}Listener}.
      */
     public static class {{listenerName}}Marshaller extends ListenerMarshaller
         implements {{listenerName}}Listener

src/test/java/com/threerings/bureau/server/RegistryTester.java

@@ -31,9 +31,10 @@ import com.google.inject.Inject;
 import com.google.inject.Injector;
 import com.google.inject.Singleton;
 
+import com.samskivert.util.Lifecycle;
+
 import com.threerings.presents.dobj.RootDObjectManager;
 import com.threerings.presents.server.PresentsSession;
-import com.threerings.presents.server.ShutdownManager;
 
 import com.threerings.bureau.data.AgentObject;
 import com.threerings.bureau.data.BureauCredentials;
@@ -87,7 +88,7 @@ public class RegistryTester
     /**
      * Creates a new registry tester.
      */
-    @Inject public RegistryTester (TestServer server, ShutdownManager shutmgr)
+    @Inject public RegistryTester (TestServer server, Lifecycle cycle)
     {
         _server = server;
 
@@ -105,7 +106,7 @@ public class RegistryTester
 
         // stop the tests when the server shuts down
         // TODO: this is not called on Ctrl-C, need a way to shut down gracefully
-        shutmgr.registerShutdowner(new ShutdownManager.Shutdowner() {
+        cycle.addComponent(new Lifecycle.ShutdownComponent() {
             public void shutdown () {
                 log.info("Shutting down tests");
                 _stop = true;

src/test/java/com/threerings/presents/data/TestMarshaller.java

@@ -41,7 +41,7 @@ public class TestMarshaller extends InvocationMarshaller
     implements TestService
 {
     /**
-     * Marshalls results to implementations of {@link TestService.TestFuncListener}.
+     * Marshalls results to implementations of {@code TestService.TestFuncListener}.
      */
     public static class TestFuncMarshaller extends ListenerMarshaller
         implements TestFuncListener
@@ -76,7 +76,7 @@ public class TestMarshaller extends InvocationMarshaller
     }
 
     /**
-     * Marshalls results to implementations of {@link TestService.TestOidListener}.
+     * Marshalls results to implementations of {@code TestService.TestOidListener}.
      */
     public static class TestOidMarshaller extends ListenerMarshaller
         implements TestOidListener