From cc943be5403c01469ca731e2ddd476f5ab83a914 Mon Sep 17 00:00:00 2001
From: akwizgran <michael@briarproject.org>
Date: Mon, 1 Jun 2020 15:30:30 +0100
Subject: [PATCH] Update javadoc.

---
 .../api/connection/ConnectionRegistry.java    | 25 +++++++++----------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/connection/ConnectionRegistry.java b/bramble-api/src/main/java/org/briarproject/bramble/api/connection/ConnectionRegistry.java
index db5968902..4ff3eb5ef 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/connection/ConnectionRegistry.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/connection/ConnectionRegistry.java
@@ -24,14 +24,6 @@ public interface ConnectionRegistry {
 	/**
 	 * Registers a connection with the given contact over the given transport.
 	 * <p>
-	 * If the registry has any connections with the same contact and a
-	 * {@link PluginConfig#getTransportPreferences() worse} transport, those
-	 * connections will be
-	 * {@link InterruptibleConnection#interruptOutgoingSession() interrupted}.
-	 * <p>
-	 * If the registry has any connections with the same contact and a better
-	 * transport, the given connection will be interrupted.
-	 * <p>
 	 * Broadcasts {@link ConnectionOpenedEvent}. Also broadcasts
 	 * {@link ContactConnectedEvent} if this is the only connection with the
 	 * contact.
@@ -54,12 +46,19 @@ public interface ConnectionRegistry {
 	 * registered via {@link #registerConnection(ContactId, TransportId,
 	 * InterruptibleConnection, boolean)}.
 	 * <p>
-	 * If the registry has any connections with the same contact and transport
-	 * and a lower {@link Priority priority}, those connections will be
-	 * {@link InterruptibleConnection#interruptOutgoingSession() interrupted}.
+	 * If the registry has any "better" connections with the given contact, the
+	 * given connection will be interrupted. If the registry has any "worse"
+	 * connections with the given contact, those connections will be
+	 * interrupted.
 	 * <p>
-	 * If the registry has any connections with the same contact and transport
-	 * and a higher priority, the given connection will be interrupted.
+	 * Connection A is considered "better" than connection B if both
+	 * connections have had their priorities set, and either A's transport is
+	 * {@link PluginConfig#getTransportPreferences() preferred} to B's, or
+	 * they use the same transport and A has higher {@link Priority priority}
+	 * than B.
+	 * <p>
+	 * For backward compatibility, connections without priorities are not
+	 * considered better or worse than other connections.
 	 */
 	void setPriority(ContactId c, TransportId t, InterruptibleConnection conn,
 			Priority priority);