Javadoc fixes

Better OCMOSJ Javadocs

router/java/src/net/i2p/router/StatisticsManager.java

@@ -63,7 +63,7 @@ public class StatisticsManager {
      *
      *  This includes all standard options (as of 0.9.24, network ID and caps)
      *
-     *  @param current router hash, non-null
+     *  @param h current router hash, non-null
      *  @since 0.9.24
      */
     public Properties publishStatistics(Hash h) { 

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

@@ -38,10 +38,67 @@ import net.i2p.router.TunnelInfo;
 import net.i2p.util.Log;
 
 /**
- * Send a client message out a random outbound tunnel and into a random inbound
+ * Send a client message out an outbound tunnel and into an inbound
  * tunnel on the target leaseSet.  This also (sometimes) bundles the sender's leaseSet and
  * a DeliveryStatusMessage (for ACKing any sessionTags used in the garlic).
  *
+ * <p>
+ * This class is where we make several important decisions about
+ * what to send and what path to send it over. These decisions
+ * will dramatically affect:
+ * <ul>
+ * <li>Local performance and outbound bandwidth usage
+ * <li>Streaming performance and reliability
+ * <li>Overall network performace and connection congestion
+ * </ul>
+ *
+ * <p>
+ * For the outbound message, we build and encrypt a garlic message,
+ * after making the following decisions:
+ * <ul>
+ * <li>Whether to bundle our leaseset
+ * <li>Whether to bundle session tags, and if so, how many
+ * <li>Whether to bundle an encrypted DeliveryStatusMessage to be returned
+ *     to us as an acknowledgement
+ * </ul>
+ *
+ * <p>
+ * Also, we make the following path selection decisions:
+ * <ul>
+ * <li>What outbound client tunnel of ours to use send the message out
+ * <li>What inbound client tunnel of his (i.e. lease, chosen from his leaseset)
+ *     to use to send the message in
+ * <li>If a DeliveryStatusMessage is bundled, What inbound client tunnel of ours
+ *     do we specify to receive it
+ * </ul>
+ *
+ * <p>
+ * Note that the 4th tunnel in the DeliveryStatusMessage's round trip (his outbound tunnel)
+ * is not selected by us, it is chosen by the recipient.
+ *
+ * <p>
+ * If a DeliveryStatusMessage is sent, a listener is registered to wait for its reply.
+ * When a reply is received, or the timeout is reached, this is noted
+ * and will influence subsequent bundling and path selection decisions.
+ *
+ * <p>
+ * Path selection decisions are cached and reused if still valid and if
+ * previous deliveries were apparently successful. This significantly
+ * reduces out-of-order delivery and network connection congestion.
+ * Caching is based on the local/remote destination pair.
+ *
+ * <p>
+ * Bundling decisions, and both messaging and reply expiration times, are generally
+ * set here but may be overridden by the client on a per-message basis.
+ * Within clients, there may be overall settings or per-message settings.
+ * The streaming lib also overrides defaults for some messages.
+ * A datagram-based DHT application may need significantly different
+ * settings than a streaming application. For an application such as
+ * a bittorrent client that sends both types of traffic on the same tunnels,
+ * it is important to tune the settings for efficiency and performance.
+ * The per-session and per-message overrides are set via I2CP.
+ *
+ *
  */
 public class OutboundClientMessageOneShotJob extends JobImpl {
     private final Log _log;

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

@@ -109,7 +109,7 @@ class OutboundEstablishState {
      *  @param claimedAddress an IP/port based RemoteHostId, or null if unknown
      *  @param remoteHostId non-null, == claimedAddress if direct, or a hash-based one if indirect
      *  @param remotePeer must have supported sig type
-     *  @param allowExtenededOptions are we allowed to send extended options to Bob?
+     *  @param allowExtendedOptions are we allowed to send extended options to Bob?
      *  @param needIntroduction should we ask Bob to be an introducer for us?
                ignored unless allowExtendedOptions is true
      *  @param introKey Bob's introduction key, as published in the netdb

router/java/src/net/i2p/router/tunnel/TunnelCreatorConfig.java

@@ -152,7 +152,6 @@ public class TunnelCreatorConfig implements TunnelInfo {
 
     /**
      *  This calls profile manager tunnelDataPushed1m() for each peer
-     *  @return null for exploratory
      */
     public synchronized void incrementVerifiedBytesTransferred(int bytes) { 
         _verifiedBytesTransferred += bytes;