From a927d55bb165d64e149d3a372a8645aa87d90a79 Mon Sep 17 00:00:00 2001
From: Florian Schmaus <flo@geekplace.eu>
Date: Thu, 12 Feb 2015 12:09:52 +0100
Subject: [PATCH] Improve XMPPConnection javadoc

It's an interface

State that it does intentionally not declare any state changing
methods (e.g. connect(), disconnect())
---
 .../org/jivesoftware/smack/XMPPConnection.java   | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java b/smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java
index bea75de21..e2e1497d5 100644
--- a/smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java
+++ b/smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java
@@ -28,7 +28,7 @@ import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smack.packet.PlainStreamElement;
 
 /**
- * The abstract XMPPConnection class provides an interface for connections to a XMPP server and
+ * The XMPPConnection interface provides an interface for connections to a XMPP server and
  * implements shared methods which are used by the different types of connections (e.g.
  * {@link XMPPTCPConnection} or {@link XMPPBOSHConnection}). To create a connection to a XMPP server
  * a simple usage of this API might look like the following:
@@ -52,11 +52,19 @@ import org.jivesoftware.smack.packet.PlainStreamElement;
  * // Disconnect from the server
  * con.disconnect();
  * </pre>
+ * </p>
  * <p>
- * Connections can be reused between connections. This means that an Connection may be connected,
- * disconnected and then connected again. Listeners of the Connection will be retained across
+ * Note that the XMPPConnection interface does intentionally not declare any methods that manipulate
+ * the connection state, e.g. <code>connect()</code>, <code>disconnect()</code>. You should use the
+ * most specific connection type, e.g. <code>XMPPTCPConnection</code> as declared type and use the
+ * XMPPConnection interface when you don't need to manipulate the connection state.
+ * </p>
+ * <p>
+ * XMPPConnections can be reused between connections. This means that an Connection may be connected,
+ * disconnected and then connected again. Listeners of the XMPPConnection will be retained across
  * connections.
- * 
+ * </p>
+ *
  * @author Matt Tucker
  * @author Guenther Niess
  */