From 2c1b9c2d370ed83be30052ad17d14a2d8fcc4f6c Mon Sep 17 00:00:00 2001
From: zzz <zzz@mail.i2p>
Date: Sat, 12 Dec 2015 14:31:52 +0000
Subject: [PATCH] Javadoc fixes Better OCMOSJ Javadocs
---
apps/sam/java/src/net/i2p/sam/SAMBridge.java | 2 +-
.../src/net/i2p/router/StatisticsManager.java | 2 +-
.../OutboundClientMessageOneShotJob.java | 59 ++++++++++++++++++-
.../transport/udp/OutboundEstablishState.java | 2 +-
.../router/tunnel/TunnelCreatorConfig.java | 1 -
5 files changed, 61 insertions(+), 5 deletions(-)
diff --git a/apps/sam/java/src/net/i2p/sam/SAMBridge.java b/apps/sam/java/src/net/i2p/sam/SAMBridge.java
index df7528c330..beb2323563 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 b1ed027426..7fc62c8386 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 fd45bc7520..b98b7a2ed5 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 d849bb836b..918033dc88 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 758d2096b9..734490d6a9 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;
--
GitLab