javadoc cleanup to remove those damn warnings

apps/i2ptunnel/java/src/net/i2p/i2ptunnel/I2PTunnel.java

@@ -252,7 +252,7 @@ public class I2PTunnel implements Logging, EventDispatcher {
     
     /**
      * Run the server pointing at the host and port specified using the private i2p
-     * destination loaded from the specified file
+     * destination loaded from the specified file. <p />
      *
      * Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error)
      * Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after
@@ -307,7 +307,7 @@ public class I2PTunnel implements Logging, EventDispatcher {
     
     /**
      * Run the server pointing at the host and port specified using the private i2p
-     * destination loaded from the given base64 stream
+     * destination loaded from the given base64 stream. <p />
      *
      * Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error)
      * Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after
@@ -353,7 +353,7 @@ public class I2PTunnel implements Logging, EventDispatcher {
     
     /**
      * Run the client on the given port number pointing at the specified destination
-     * (either the base64 of the destination or file:fileNameContainingDestination)
+     * (either the base64 of the destination or file:fileNameContainingDestination).
      *
      * Sets the event "clientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error)
      * Also sets the event "openClientResult" = "error" or "ok" (before setting the value to "ok" it also

apps/i2ptunnel/java/src/net/i2p/i2ptunnel/I2PTunnelRunner.java

@@ -62,8 +62,9 @@ public class I2PTunnelRunner extends Thread {
     public boolean isFinished() { return finished; }
     
     /** 
-     * When was the last data for this runner sent or received?  (-1 if no data
+     * When was the last data for this runner sent or received?  
-     * has been transferred yet)
+     *
+     * @return date (ms since the epoch), or -1 if no data has been transferred yet
      *
      */
     public long getLastActivityOn() { return lastActivityOn; }

core/java/src/net/i2p/client/ATalk.java

@@ -225,7 +225,7 @@ public class ATalk implements I2PSessionListener, Runnable {
     /** I2PSessionListener.messageAvailable requires this method to be called whenever
      * I2P wants to tell the session that a message is available.  ATalk always grabs
      * the message immediately and either processes it as a "send file" command (passing
-     * it off to {@link #handleRecieveFile handleRecieveFile}) or simply displays the
+     * it off to handleRecieveFile(..) or simply displays the
      * message to the user.
      *
      */

core/java/src/net/i2p/client/I2PSession.java

@@ -32,7 +32,9 @@ public interface I2PSession {
     public boolean sendMessage(Destination dest, byte[] payload) throws I2PSessionException;
     /**
      * Like sendMessage above, except the key used and the tags sent are exposed to the 
-     * application, so that if some application layer message delivery confirmation is used,
+     * application.  <p /> 
+     * 
+     * If some application layer message delivery confirmation is used,
      * rather than i2p's (slow) built in confirmation via guaranteed delivery mode, the 
      * application can update the SessionKeyManager, ala:
      * <pre>

core/java/src/net/i2p/client/TestServer.java

@@ -55,7 +55,7 @@ public class TestServer implements Runnable {
     }
     
     /**
-     * Handle the connection by passing it off to a {@link ConnectionRunner ConnectionRunner}
+     * Handle the connection by passing it off to a ConnectionRunner
      *
      */
     protected void runConnection(Socket socket) throws IOException {

core/java/src/net/i2p/crypto/AESEngine.java

@@ -23,8 +23,7 @@ import java.io.ByteArrayInputStream;
  * Wrapper singleton for AES cypher operation.
  *
  * @author jrandom
- * @license GPL
+  */
- */
 public class AESEngine {
     private final static Log _log = new Log(AESEngine.class);
     private static AESEngine _engine;

core/java/src/net/i2p/crypto/CryptixAESEngine.java

@@ -20,8 +20,7 @@ import net.i2p.util.Log;
  * Only supports data of size mod 16 bytes - no inherent padding.
  *
  * @author jrandom, thecrypto
- * @license GPL
+  */
- */
 public class CryptixAESEngine extends AESEngine {
     private final static Log _log = new Log(CryptixAESEngine.class);
     private final static CryptixRijndael_Algorithm _algo = new CryptixRijndael_Algorithm();

core/java/src/net/i2p/crypto/DummyElGamalEngine.java

@@ -21,7 +21,6 @@ import net.i2p.util.Log;
  * Fake ElG E and D, useful for when performance isn't being tested
  *
  * @author jrandom
- * @license GPL
  */
 public class DummyElGamalEngine extends ElGamalEngine {
     private final static Log _log = new Log(DummyElGamalEngine.class);    

core/java/src/net/i2p/data/DataHelper.java

@@ -338,9 +338,10 @@ public class DataHelper {
 
     
     /**
-     * Helper util to compare two objects, treating (null == null) as true, and 
+     * Helper util to compare two objects, including null handling.
-     * (null == (!null)) as false.
+     * <p />
      *
+     * This treats (null == null) as true, and (null == (!null)) as false.
      */
     public final static boolean eq(Object lhs, Object rhs) {
 	try {
@@ -353,8 +354,12 @@ public class DataHelper {
 	}
     }
     /**
-     * Deep compare two collections, treating (null == null) as true,
+     * Run a deep comparison across the two collections.  
-     * (null == (!null)) as false, and then comparing each element via eq(object, object).
+     * <p />
+     *
+     * This treats (null == null) as true, (null == (!null)) as false, and then 
+     * comparing each element via eq(object, object). <p />
+     *
      * If the size of the collections are not equal, the comparison returns false.
      * The collection order should be consistent, as this simply iterates across both and compares
      * based on the value of each at each step along the way.
@@ -373,8 +378,10 @@ public class DataHelper {
     }
     
     /**
-     * Compare the byte arrays byte by byte, treating (null == null) as
+     * Run a comparison on the byte arrays, byte by byte.  <p />
-     * true, (null == (!null)) as false, and unequal length arrays as false.
+     *
+     * This treats (null == null) as true, (null == (!null)) as false, 
+     * and unequal length arrays as false.
      *
      */
     public final static boolean eq(byte lhs[], byte rhs[]) {

core/java/src/net/i2p/data/Payload.java

@@ -16,7 +16,7 @@ import net.i2p.util.Log;
 
 /**
  * Defines the actual payload of a message being delivered, including the 
- * standard encryption wrapping, as defined by the I2P data structure spec.<p />
+ * standard encryption wrapping, as defined by the I2P data structure spec.
  *
  * @author jrandom
  */

core/java/src/net/i2p/data/RouterAddress.java

@@ -39,7 +39,7 @@ public class RouterAddress extends DataStructureImpl {
     
     /**
      * Retrieve the weighted cost of this address, relative to other methods of
-     * contacting this router.  0 means free and 255 means really expensive.
+     * contacting this router.  The value 0 means free and 255 means really expensive.
      * No value above 255 is allowed.
      *
      */

core/java/src/net/i2p/data/TunnelId.java

@@ -41,8 +41,7 @@ public class TunnelId extends DataStructureImpl {
     public void setTunnelId(long id) { _tunnelId = id; }
     
     /** 
-     * contains the metadata for the tunnel - is it inbound, outbound, or a participant? 
+     * is this tunnel inbound, outbound, or a participant (kept in memory only and used only for the router).s
-     * This data point is kept in memory only and is useful for the router.
      *
      * @return type of tunnel (per constants TYPE_UNSPECIFIED, TYPE_INBOUND, TYPE_OUTBOUND, TYPE_PARTICIPANT)
      */

core/java/src/net/i2p/data/i2cp/I2CPMessageImpl.java

@@ -28,8 +28,7 @@ public abstract class I2CPMessageImpl extends DataStructureImpl implements I2CPM
     public I2CPMessageImpl() {}
     
     /**
-     * Validate the type and size of the message. and then read the message 
+     * Validate the type and size of the message, and then read the message into the data structures.  <p />
-     * into the data structures. 
      *
      */
     public void readMessage(InputStream in) throws I2CPMessageException, IOException {

core/java/src/net/i2p/stat/Rate.java

@@ -93,8 +93,8 @@ public class Rate {
     
     /**
      * Create a new rate and load its state from the properties, taking data 
-     * from the data points underneath the given prefix (e.g. prefix = 
+     * from the data points underneath the given prefix.  <p />
-     * "profile.dbIntroduction.60m", this will load the associated data points such
+     * (e.g. prefix = "profile.dbIntroduction.60m", this will load the associated data points such
      * as "profile.dbIntroduction.60m.lifetimeEventCount").  The data can be exported
      * through store(outputStream, "profile.dbIntroduction.60m").
      *
@@ -189,7 +189,7 @@ public class Rate {
      * During the last period, how much of the time was spent actually processing events in proportion 
      * to how many events could have occurred if there were no intervals?
      *
-     * If this statistic doesn't use event times, this returns 0.
+     * @return percentage, or 0 if event times aren't used
      */
     public double getLastEventSaturation() {
 	if ( (_lastEventCount > 0) && (_lastTotalEventTime > 0) ) {
@@ -203,10 +203,10 @@ public class Rate {
     }
     
     /** 
-     * During the extreme period, how much of the time was spent actually processing events in proportion 
+     * During the extreme period, how much of the time was spent actually processing events
-     * to how many events could have occurred if there were no intervals?
+     * in proportion to how many events could have occurred if there were no intervals? 
      *
-     * If this statistic doesn't use event times, this returns 0.
+     * @return percentage, or 0 if the statistic doesn't use event times
      */
     public double getExtremeEventSaturation() {
 	if ( (_extremeEventCount > 0) && (_extremeTotalEventTime > 0) ) {
@@ -222,7 +222,7 @@ public class Rate {
      * During the lifetime of this stat, how much of the time was spent actually processing events in proportion 
      * to how many events could have occurred if there were no intervals? 
      *
-     * If this statistic doesn't use event times, this returns 0.
+     * @return percentage, or 0 if event times aren't used
      */
     public double getLifetimeEventSaturation() {
 	if ( (_lastEventCount > 0) && (_lifetimeTotalEventTime > 0) ) {
@@ -244,9 +244,10 @@ public class Rate {
     }
     
     /** 
-     * using the last period's rate, what is the total value that could have been sent if events were constant? 
+     * using the last period's rate, what is the total value that could have been sent 
-     * If this statistic's event times are 0, this returns 0.
+     * if events were constant?
      *
+     * @return max total value, or 0 if event times aren't used
      */
     public double getLastSaturationLimit() {
 	if ( (_lastTotalValue != 0) && (_lastEventCount > 0) && (_lastTotalEventTime > 0) ) {
@@ -261,9 +262,10 @@ public class Rate {
     }
     
     /** 
-     * using the extreme period's rate, what is the total value that could have been sent if events were constant? 
+     * using the extreme period's rate, what is the total value that could have been 
-     * If this statistic's event times are 0, this returns 0.
+     * sent if events were constant?
      *
+     * @return event total at saturation, or 0 if no event times are measured
      */
     public double getExtremeSaturationLimit() {
 	if ( (_extremeTotalValue != 0) && (_extremeEventCount > 0) && (_extremeTotalEventTime > 0) ) {

router/java/src/net/i2p/router/message/SendReplyMessageJob.java

@@ -45,10 +45,10 @@ public class SendReplyMessageJob extends JobImpl {
     }
     
     /**
-     * Send the message on its way.<p />
+     * Send the message on its way. <p />
      *
      * This could garlic route the message to the _block.getRouter, or it could
-     * send it there via a tunnel, or it could just send it direct.<p />
+     * send it there via a tunnel, or it could just send it direct. <p />
      *
      * For simplicity, its currently going direct.
      *

router/java/src/net/i2p/router/peermanager/DBHistory.java

@@ -64,7 +64,10 @@ public class DBHistory {
     public long getUnpromptedDbStoreNew() { return _unpromptedDbStoreNew; }
     /** how many times have they sent us data we didn't ask for but that we have seen? */
     public long getUnpromptedDbStoreOld() { return _unpromptedDbStoreOld; }
-    /** how often does the peer fail to reply to a lookup request?  1 hour and 1 day periods */
+    /** 
+     * how often does the peer fail to reply to a lookup request, broken into 1 hour and 1 day periods.
+     *
+     */
     public RateStat getFailedLookupRate() { return _failedLookupRate; }
 
     /**