diff --git a/apps/sam/java/src/net/i2p/sam/SAMBridge.java b/apps/sam/java/src/net/i2p/sam/SAMBridge.java
index df7528c3304d59c46eceed7ac3c39845d87c0fc9..beb23235639dd30099c103c6e27f9415a06afb88 100644
--- a/apps/sam/java/src/net/i2p/sam/SAMBridge.java
+++ b/apps/sam/java/src/net/i2p/sam/SAMBridge.java
@@ -359,7 +359,7 @@ public class SAMBridge implements Runnable, ClientApp {
      * TODO we could have multiple servers on different hosts/ports in the future.
      *
      * @param props non-null instantiate and start server if it doesn't exist
-     * @param return non-null
+     * @return non-null
      * @throws IOException if can't bind to host/port, or if different than existing
      * @since 0.9.24
      */
diff --git a/router/java/src/net/i2p/router/StatisticsManager.java b/router/java/src/net/i2p/router/StatisticsManager.java
index b1ed027426e0137a2d9cf07ae4b12890631735d5..7fc62c83862f1a4bafbb28ee8b6feba451aadd7b 100644
--- a/router/java/src/net/i2p/router/StatisticsManager.java
+++ b/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) { 
diff --git a/router/java/src/net/i2p/router/message/OutboundClientMessageOneShotJob.java b/router/java/src/net/i2p/router/message/OutboundClientMessageOneShotJob.java
index fd45bc7520fe01c2df19026c03262bad5f76ee5f..b98b7a2ed5411280b11c42c64904dd3fdd618414 100644
--- a/router/java/src/net/i2p/router/message/OutboundClientMessageOneShotJob.java
+++ b/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;
diff --git a/router/java/src/net/i2p/router/transport/udp/OutboundEstablishState.java b/router/java/src/net/i2p/router/transport/udp/OutboundEstablishState.java
index d849bb836b31356675e0349e639706aa43ed458d..918033dc88a0b3584611824948ea126ce244b60a 100644
--- a/router/java/src/net/i2p/router/transport/udp/OutboundEstablishState.java
+++ b/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
diff --git a/router/java/src/net/i2p/router/tunnel/TunnelCreatorConfig.java b/router/java/src/net/i2p/router/tunnel/TunnelCreatorConfig.java
index 758d2096b99a5042f0201577c772075239207ff0..734490d6a9d6c8009021194950623cbc1dcd0383 100644
--- a/router/java/src/net/i2p/router/tunnel/TunnelCreatorConfig.java
+++ b/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;