Merge branch '4.1.x-stable' into 4.2.x-stable

Author: michaelklishin

src/main/java/com/rabbitmq/client/ConnectionFactory.java

@@ -986,7 +986,8 @@ public Connection newConnection() throws IOException, TimeoutException {
      * is enabled, the connection returned by this method will be {@link Recoverable}. Reconnection
      * attempts will always use the address configured on {@link ConnectionFactory}.
      *
-     * @param connectionName arbitrary sring for connection name client property
+     * @param connectionName client-provided connection name (an arbitrary string). Will
+     *                       be displayed in management UI if the server supports it.
      * @return an interface to the connection
      * @throws IOException if it encounters a problem
      */
@@ -1017,7 +1018,8 @@ public Connection newConnection(ExecutorService executor) throws IOException, Ti
      * attempts will always use the address configured on {@link ConnectionFactory}.
      *
      * @param executor thread execution service for consumers on the connection
-     * @param connectionName arbitrary sring for connection name client property
+     * @param connectionName client-provided connection name (an arbitrary string). Will
+     *                       be displayed in management UI if the server supports it.
      * @return an interface to the connection
      * @throws IOException if it encounters a problem
      */

src/main/java/com/rabbitmq/client/RecoveryListener.java

@@ -22,6 +22,18 @@
  * @since 3.3.0
  */
 public interface RecoveryListener {
+    /**
+     * Invoked when automatic connection recovery has completed.
+     * This includes topology recovery if it was enabled.
+     * @param recoverable a {@link Recoverable} connection.
+     */
     void handleRecovery(Recoverable recoverable);
+
+    /**
+     * Invoked before automatic connection recovery starts.
+     * This means no recovery steps were performed at this point
+     * during recovery process.
+     * @param recoverable a {@link Recoverable} connection.
+     */
     void handleRecoveryStarted(Recoverable recoverable);
 }