javadoc, comment out some main()s

core/java/src/net/i2p/I2PAppContext.java

@@ -210,6 +210,7 @@ public class I2PAppContext {
     *  need to look there as well.
     *
     *  All dirs except the base are created if they don't exist, but the creation will fail silently.
+    *  @since 0.7.6
     */
     private void initializeDirs() {
         String s = getProperty("i2p.dir.base", System.getProperty("user.dir"));
@@ -265,12 +266,78 @@ public class I2PAppContext {
         ******/
     }
 
+    /**
+     *  This is the installation dir, often referred to as $I2P.
+     *  Applilcations should consider this directory read-only and never
+     *  attempt to write to it.
+     *  It may actually be read-only on a multi-user installation.
+     *  The config files in this directory are templates for user
+     *  installations and should not be accessed by applications.
+     *  The only thing that may be useful in here is the lib/ dir
+     *  containing the .jars.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getBaseDir() { return _baseDir; }
+
+    /**
+     *  The base dir for config files.
+     *  Applications may use this to access router configuration files if necessary.
+     *  Usually ~/.i2p on Linux and %APPDIR%\I2P on Windows.
+     *  In installations originally installed with 0.7.5 or earlier, and in
+     *  "portable" installations, this will be the same as the base dir.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getConfigDir() { return _configDir; }
+
+    /**
+     *  Where the router keeps its files.
+     *  Applications should not use this.
+     *  The same as the config dir for now.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getRouterDir() { return _routerDir; }
+
+    /**
+     *  Where router.ping goes.
+     *  Applications should not use this.
+     *  The same as the system temp dir for now.
+     *  Which is a problem for multi-user installations.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getPIDDir() { return _pidDir; }
+
+    /**
+     *  Where the router keeps its log directory.
+     *  Applications should not use this.
+     *  The same as the config dir for now.
+     *  (i.e. ~/.i2p, NOT ~/.i2p/logs)
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getLogDir() { return _logDir; }
+
+    /**
+     *  Where applications may store data.
+     *  The same as the config dir for now, but may change in the future.
+     *  Apps should be careful not to overwrite router files.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getAppDir() { return _appDir; }
+
+    /**
+     *  Where anybody may store temporary data.
+     *  This is a directory created in the system temp dir on the
+     *  first call in this context, and is deleted on JVM exit.
+     *  Applications should create their own directory inside this directory
+     *  to avoid collisions with other apps.
+     *  @since 0.7.6
+     *  @return dir constant for the life of the context
+     */
     public File getTempDir() {
         // fixme don't synchronize every time
         synchronized (this) {

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

@@ -18,7 +18,8 @@ import net.i2p.util.RandomSource;
 
 /** 
  * Dummy wrapper for AES cipher operation.
- *
+ * UNUSED unless i2p.encryption = off
+ * See CryptixAESEngine for the real thing.
  */
 public class AESEngine {
     private Log _log;
@@ -145,7 +146,10 @@ public class AESEngine {
         _log.warn("Warning: AES is disabled");
     }
 
-    
+    /**
+     *   Just copies payload to out
+     *   @param sessionKey unused
+     */
     public void encryptBlock(byte payload[], int inIndex, SessionKey sessionKey, byte out[], int outIndex) {
         System.arraycopy(payload, inIndex, out, outIndex, out.length - outIndex);
     }
@@ -158,6 +162,7 @@ public class AESEngine {
         System.arraycopy(payload, inIndex, rv, outIndex, rv.length - outIndex);
     }
     
+/******
     public static void main(String args[]) {
         I2PAppContext ctx = new I2PAppContext();
         SessionKey key = ctx.keyGenerator().generateSessionKey();
@@ -178,4 +183,5 @@ public class AESEngine {
         byte ld[] = ctx.aes().safeDecrypt(le, key, iv);
         ctx.logManager().getLog(AESEngine.class).debug("Long test: " + DataHelper.eq(ld, lbuf));
     }
+******/
 }

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

@@ -126,6 +126,7 @@ public class CryptixAESEngine extends AESEngine {
         _prevCache.release(curA);
     }
     
+    /** encrypt exactly 16 bytes using the session key */
     @Override
     public final void encryptBlock(byte payload[], int inIndex, SessionKey sessionKey, byte out[], int outIndex) {
         if (sessionKey.getPreparedKey() == null) {
@@ -166,6 +167,7 @@ public class CryptixAESEngine extends AESEngine {
         CryptixRijndael_Algorithm.blockDecrypt(payload, rv, inIndex, outIndex, sessionKey.getPreparedKey(), 16);
     }
     
+/********
     public static void main(String args[]) {
         I2PAppContext ctx = new I2PAppContext();
         try {
@@ -278,4 +280,5 @@ public class CryptixAESEngine extends AESEngine {
         else
             System.out.println("block D(E(orig)) == orig");
     }
+*******/
 }

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

@@ -66,10 +66,10 @@ public class ElGamalEngine {
     public ElGamalEngine(I2PAppContext context) {
         context.statManager().createRateStat("crypto.elGamal.encrypt",
                                              "how long does it take to do a full ElGamal encryption", "Encryption",
-                                             new long[] { 60 * 1000, 60 * 60 * 1000, 24 * 60 * 60 * 1000});
+                                             new long[] { 60 * 60 * 1000});
         context.statManager().createRateStat("crypto.elGamal.decrypt",
                                              "how long does it take to do a full ElGamal decryption", "Encryption",
-                                             new long[] { 60 * 1000, 60 * 60 * 1000, 24 * 60 * 60 * 1000});
+                                             new long[] { 60 * 60 * 1000});
         _context = context;
         _log = context.logManager().getLog(ElGamalEngine.class);
     }
@@ -85,9 +85,9 @@ public class ElGamalEngine {
     }
 
     /** encrypt the data to the public key
-     * @return encrypted data
+     * @return encrypted data, will be about twice as big as the cleartext
      * @param publicKey public key encrypt to
-     * @param data data to encrypt
+     * @param data data to encrypt, must be 222 bytes or less
      */
     public byte[] encrypt(byte data[], PublicKey publicKey) {
         if ((data == null) || (data.length >= 223))
@@ -156,7 +156,7 @@ public class ElGamalEngine {
     }
 
     /** Decrypt the data
-     * @param encrypted encrypted data
+     * @param encrypted encrypted data, must be 514 bytes or less
      * @param privateKey private key to decrypt with
      * @return unencrypted data
      */

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

@@ -25,7 +25,7 @@ import net.i2p.util.Log;
 import net.i2p.util.NativeBigInteger;
 import net.i2p.util.RandomSource;
 
-/** Define a way of generating asymetrical key pairs as well as symetrical keys
+/** Define a way of generating asymmetrical key pairs as well as symmetrical keys
  * @author jrandom
  */
 public class KeyGenerator {
@@ -157,7 +157,7 @@ public class KeyGenerator {
      * Pad the buffer w/ leading 0s or trim off leading bits so the result is the
      * given length.  
      */
-    final static byte[] padBuffer(byte src[], int length) {
+    private final static byte[] padBuffer(byte src[], int length) {
         byte buf[] = new byte[length];
 
         if (src.length > buf.length) // extra bits, chop leading bits
@@ -171,6 +171,7 @@ public class KeyGenerator {
         return buf;
     }
 
+/******
     public static void main(String args[]) {
         Log log = new Log("keygenTest");
         RandomSource.getInstance().nextBoolean();
@@ -222,4 +223,5 @@ public class KeyGenerator {
         } catch (InterruptedException ie) { // nop
         }
     }
+******/
 }

router/java/src/net/i2p/router/transport/udp/UDPPacketReader.java

@@ -598,6 +598,8 @@ public class UDPPacketReader {
                 _log.debug("read alice port: " + rv);
             return rv;
         }
+
+        /** unused */
         public int readChallengeSize() {
             int offset = readBodyOffset() + 4;
             offset += DataHelper.fromLong(_message, offset, 1);
@@ -608,6 +610,8 @@ public class UDPPacketReader {
                 _log.debug("read challenge size: " + rv);
             return rv;
         }
+
+        /** unused */
         public void readChallengeSize(byte target[], int targetOffset) {
             int offset = readBodyOffset() + 4;
             offset += DataHelper.fromLong(_message, offset, 1);
@@ -668,6 +672,8 @@ public class UDPPacketReader {
             offset++;
             return (int)DataHelper.fromLong(_message, offset, 2);
         }
+
+        /** unused */
         public int readChallengeSize() {
             int offset = readBodyOffset();
             offset += DataHelper.fromLong(_message, offset, 1);
@@ -675,6 +681,8 @@ public class UDPPacketReader {
             offset += 2;
             return (int)DataHelper.fromLong(_message, offset, 1);
         }
+
+        /** unused */
         public void readChallengeSize(byte target[], int targetOffset) {
             int offset = readBodyOffset();
             offset += DataHelper.fromLong(_message, offset, 1);