Fix javadoc issues in some packages

smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java

@@ -1017,6 +1017,11 @@ public abstract class AbstractXMPPConnection implements XMPPConnection {
 
     private SmackConfiguration.UnknownIqRequestReplyMode unknownIqRequestReplyMode = SmackConfiguration.getUnknownIqRequestReplyMode();
 
+    /**
+     * Set how Smack behaves when an unknown IQ request has been received.
+     *
+     * @param unknownIqRequestReplyMode reply mode.
+     */
     public void setUnknownIqRequestReplyMode(UnknownIqRequestReplyMode unknownIqRequestReplyMode) {
         this.unknownIqRequestReplyMode = Objects.requireNonNull(unknownIqRequestReplyMode, "Mode must not be null");
     }
@@ -1026,8 +1031,8 @@ public abstract class AbstractXMPPConnection implements XMPPConnection {
      * {@link org.jivesoftware.smack.packet.XMPPError.Condition#feature_not_implemented} when a request IQ without a
      * registered {@link IQRequestHandler} is received.
      *
-     * @param replyToUnknownIq
-     * @deprecated use {@link #setUnknownIqRequestReplyMode(UnknownIqRequestReplyMode)} instead.
+     * @param replyToUnknownIq whether Smack should reply to unknown IQs or not.
+     * @deprecated use {@link AbstractXMPPConnection#setUnknownIqRequestReplyMode(UnknownIqRequestReplyMode)} instead.
      */
     @Deprecated
     // TODO Remove in Smack 4.3

smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java

@@ -881,6 +881,7 @@ public abstract class ConnectionConfiguration {
          * argument. It also calls {@link #allowEmptyOrNullUsernames()} and {@link #setSecurityMode(ConnectionConfiguration.SecurityMode)} to
          * {@link SecurityMode#required}.
          *
+         * @param sslContext custom SSLContext to be used.
          * @return a reference to this builder.
          */
         public B performSaslExternalAuthentication(SSLContext sslContext) {

smack-core/src/main/java/org/jivesoftware/smack/SASLAuthentication.java

@@ -260,6 +260,7 @@ public final class SASLAuthentication {
     /**
      * Notification message saying that SASL authentication was successful. The next step
      * would be to bind the resource.
+     * @param success result of the authentication.
      * @throws SmackException 
      * @throws InterruptedException 
      */

smack-core/src/main/java/org/jivesoftware/smack/SmackConfiguration.java

@@ -295,6 +295,8 @@ public final class SmackConfiguration {
      * of a TLS certificate. XMPP connections are able to overwrite this settings by supplying a
      * HostnameVerifier in their ConnectionConfiguration with
      * {@link ConnectionConfiguration.Builder#setHostnameVerifier(HostnameVerifier)}.
+     *
+     * @param verifier HostnameVerifier
      */
     public static void setDefaultHostnameVerifier(HostnameVerifier verifier) {
         defaultHostnameVerififer = verifier;

smack-core/src/main/java/org/jivesoftware/smack/StanzaCollector.java

@@ -109,6 +109,7 @@ public class StanzaCollector {
      * immediately returns <tt>null</tt> if no packets are currently in the
      * result queue.
      *
+     * @param <P> type of the result stanza.
      * @return the next stanza(/packet) result, or <tt>null</tt> if there are no more
      *      results.
      */
@@ -124,7 +125,8 @@ public class StanzaCollector {
      * <p>
      * Throws an XMPPErrorException in case the polled stanzas did contain an XMPPError.
      * </p>
-     * 
+     *
+     * @param <P> type of the result stanza.
      * @return the next available packet.
      * @throws XMPPErrorException in case an error response.
      */
@@ -139,7 +141,8 @@ public class StanzaCollector {
     /**
      * Returns the next available packet. The method call will block (not return) until a stanza(/packet) is
      * available.
-     * 
+     *
+     * @param <P> type of the result stanza.
      * @return the next available packet.
      * @throws InterruptedException 
      */
@@ -156,7 +159,8 @@ public class StanzaCollector {
     /**
      * Returns the next available packet. The method call will block until the connection's default
      * timeout has elapsed.
-     * 
+     *
+     * @param <P> type of the result stanza.
      * @return the next available packet.
      * @throws InterruptedException 
      */
@@ -171,6 +175,7 @@ public class StanzaCollector {
      * until a stanza(/packet) is available or the <tt>timeout</tt> has elapsed. If the
      * timeout elapses without a result, <tt>null</tt> will be returned.
      *
+     * @param <P> type of the result stanza.
      * @param timeout the timeout in milliseconds.
      * @return the next available packet.
      * @throws InterruptedException 
@@ -195,7 +200,8 @@ public class StanzaCollector {
      * Returns the next available stanza. The method in equivalent to
      * {@link #nextResultOrThrow(long)} where the timeout argument is the default reply timeout of
      * the connection associated with this collector.
-     * 
+     *
+     * @param <P> type of the result stanza.
      * @return the next available stanza.
      * @throws XMPPErrorException in case an error response was received.
      * @throws NoResponseException if there was no response from the server.
@@ -236,6 +242,7 @@ public class StanzaCollector {
      * </p>
      *
      * @param timeout the amount of time to wait for the next stanza in milliseconds.
+     * @param <P> type of the result stanza.
      * @return the next available stanza.
      * @throws NoResponseException if there was no response from the server.
      * @throws XMPPErrorException in case an error response was received.

smack-core/src/main/java/org/jivesoftware/smack/SynchronizationPoint.java

@@ -68,6 +68,7 @@ public class SynchronizationPoint<E extends Exception> {
      * @param request the plain stream element to send.
      * @throws NoResponseException if no response was received.
      * @throws NotConnectedException if the connection is not connected.
+     * @throws InterruptedException if the connection is interrupted.
      * @return <code>null</code> if synchronization point was successful, or the failure Exception.
      */
     public E sendAndWaitForResponse(TopLevelStreamElement request) throws NoResponseException,
@@ -101,6 +102,7 @@ public class SynchronizationPoint<E extends Exception> {
      * @throws E if an failure was reported.
      * @throws NoResponseException if no response was received.
      * @throws NotConnectedException if the connection is not connected.
+     * @throws InterruptedException if the connection is interrupted.
      */
     public void sendAndWaitForResponseOrThrow(Nonza request) throws E, NoResponseException,
                     NotConnectedException, InterruptedException {
@@ -120,7 +122,7 @@ public class SynchronizationPoint<E extends Exception> {
      * Check if this synchronization point is successful or wait the connections reply timeout.
      * @throws NoResponseException if there was no response marking the synchronization point as success or failed.
      * @throws E if there was a failure
-     * @throws InterruptedException 
+     * @throws InterruptedException if the connection is interrupted.
      */
     public void checkIfSuccessOrWaitOrThrow() throws NoResponseException, E, InterruptedException {
         checkIfSuccessOrWait();

smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java

@@ -44,13 +44,13 @@ import org.jxmpp.jid.EntityFullJid;
  * // Most servers require you to login before performing other tasks.
  * con.login("jsmith", "mypass");
  * // Start a new conversation with John Doe and send him a message.
- * Chat chat = ChatManager.getInstanceFor(con).createChat(<font color="green">"jdoe@igniterealtime.org"</font>, new MessageListener() {
+ * Chat chat = ChatManager.getInstanceFor(con).createChat("jdoe@igniterealtime.org", new MessageListener() {
  *     public void processMessage(Chat chat, Message message) {
  *         // Print out any messages we get back to standard out.
- *         System.out.println(<font color="green">"Received message: "</font> + message);
+ *         System.out.println("Received message: " + message);
  *     }
  * });
- * chat.sendMessage(<font color="green">"Howdy!"</font>);
+ * chat.sendMessage("Howdy!");
  * // Disconnect from the server
  * con.disconnect();
  * </pre>
@@ -484,7 +484,8 @@ public interface XMPPConnection {
     /**
      * Get the feature stanza(/packet) extensions for a given stream feature of the
      * server, or <code>null</code> if the server doesn't support that feature.
-     * 
+     *
+     * @param <F> {@link ExtensionElement} type of the feature.
      * @param element
      * @param namespace
      * @return a stanza(/packet) extensions of the feature or <code>null</code>

smack-core/src/main/java/org/jivesoftware/smack/XMPPException.java

@@ -90,7 +90,8 @@ public abstract class XMPPException extends Exception {
 
         /**
          * Creates a new XMPPErrorException with the XMPPError that was the root case of the exception.
-         * 
+         *
+         * @param stanza stanza that contained the exception.
          * @param error the root cause of the exception.
          */
         public XMPPErrorException(Stanza stanza, XMPPError error) {

smack-core/src/main/java/org/jivesoftware/smack/debugger/SmackDebugger.java

@@ -64,6 +64,7 @@ public interface SmackDebugger {
      * needs to wrap the new reader and writer to keep being notified of the connection
      * traffic.
      *
+     * @param reader connection reader.
      * @return a new special Reader that wraps the new connection Reader.
      */
     public abstract Reader newConnectionReader(Reader reader);
@@ -74,6 +75,7 @@ public interface SmackDebugger {
      * needs to wrap the new reader and writer to keep being notified of the connection
      * traffic.
      *
+     * @param writer connection writer.
      * @return a new special Writer that wraps the new connection Writer.
      */
     public abstract Writer newConnectionWriter(Writer writer);

smack-core/src/main/java/org/jivesoftware/smack/debugger/SmackDebuggerFactory.java

@@ -27,6 +27,11 @@ public interface SmackDebuggerFactory {
     /**
      * Initialize the new SmackDebugger instance.
      *
+     * @param connection connection.
+     * @param writer connection writer.
+     * @param reader connection reader.
+     *
+     * @return SmackDebugger.
      * @throws IllegalArgumentException if the SmackDebugger can't be loaded.
      */
     SmackDebugger create(XMPPConnection connection, Writer writer, Reader reader) throws IllegalArgumentException;

smack-core/src/main/java/org/jivesoftware/smack/filter/FromMatchesFilter.java

@@ -52,6 +52,7 @@ public final class FromMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter for the "from" address.
      */
     public static FromMatchesFilter create(Jid address) {
         return new FromMatchesFilter(address, address != null ? address.hasNoResource() : false) ;
@@ -63,6 +64,7 @@ public final class FromMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter matching the "from" address.
      */
     public static FromMatchesFilter createBare(Jid address) {
         return new FromMatchesFilter(address, true);
@@ -74,6 +76,7 @@ public final class FromMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter matching the "from" address.
      */
     public static FromMatchesFilter createFull(Jid address) {
         return new FromMatchesFilter(address, false);

smack-core/src/main/java/org/jivesoftware/smack/filter/IQReplyFilter.java

@@ -81,6 +81,7 @@ public class IQReplyFilter implements StanzaFilter {
      * and following discussion in February and March.
      *
      * @param iqPacket An IQ request. Filter for replies to this packet.
+     * @param conn connection.
      */
     public IQReplyFilter(IQ iqPacket, XMPPConnection conn) {
         if (!iqPacket.isRequestIQ()) {

smack-core/src/main/java/org/jivesoftware/smack/filter/ToMatchesFilter.java

@@ -35,6 +35,7 @@ public final class ToMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter matching the "to" address.
      */
     public static ToMatchesFilter create(Jid address) {
         return new ToMatchesFilter(address, address != null ? address.hasNoResource() : false) ;
@@ -46,6 +47,7 @@ public final class ToMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter matching the "to" address.
      */
     public static ToMatchesFilter createBare(Jid address) {
         return new ToMatchesFilter(address, true);
@@ -57,6 +59,7 @@ public final class ToMatchesFilter extends AbstractFromToMatchesFilter {
      *
      * @param address The address to filter for. If <code>null</code> is given, the stanza must not
      *        have a from address.
+     * @return filter matching the "to" address.
      */
     public static ToMatchesFilter createFull(Jid address) {
         return new ToMatchesFilter(address, false);

smack-core/src/main/java/org/jivesoftware/smack/packet/AbstractError.java

@@ -96,6 +96,7 @@ public class AbstractError {
      *
      * @param elementName the XML element name of the stanza(/packet) extension.
      * @param namespace the XML element namespace of the stanza(/packet) extension.
+     * @param <PE> type of the ExtensionElement.
      * @return the extension, or <tt>null</tt> if it doesn't exist.
      */
     public <PE extends ExtensionElement> PE getExtension(String elementName, String namespace) {

smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java

@@ -171,6 +171,7 @@ public interface Packet extends TopLevelStreamElement {
      *
      * @param elementName the XML element name of the stanza(/packet) extension. (May be null)
      * @param namespace the XML element namespace of the stanza(/packet) extension.
+     * @param <PE> type of the ExtensionElement.
      * @return the extension, or <tt>null</tt> if it doesn't exist.
      */
     <PE extends ExtensionElement> PE getExtension(String elementName, String namespace);

smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java

@@ -351,6 +351,7 @@ public abstract class Stanza implements TopLevelStreamElement {
      *
      * @param elementName the XML element name of the extension. (May be null)
      * @param namespace the XML element namespace of the extension.
+     * @param <PE> type of the ExtensionElement.
      * @return the extension, or <tt>null</tt> if it doesn't exist.
      */
     @SuppressWarnings("unchecked")

smack-core/src/main/java/org/jivesoftware/smack/packet/XMPPError.java

@@ -109,7 +109,7 @@ public class XMPPError extends AbstractError {
     /**
      * Create a new XMPPError.
      *
-     * @param condition
+     * @param condition error condition.
      * @deprecated use {@link Builder} instead.
      */
     @Deprecated
@@ -120,8 +120,8 @@ public class XMPPError extends AbstractError {
     /**
      * Create a new XMPPError.
      *
-     * @param condition
-     * @param applicationSpecificCondition
+     * @param condition error condition.
+     * @param applicationSpecificCondition application specific condition.
      * @deprecated use {@link Builder} instead.
      */
     @Deprecated
@@ -137,6 +137,8 @@ public class XMPPError extends AbstractError {
      * 
      * @param type the error type.
      * @param condition the error condition.
+     * @param conditionText
+     * @param errorGenerator
      * @param descriptiveTexts 
      * @param extensions list of stanza(/packet) extensions
      * @deprecated use {@link Builder} instead.
@@ -155,6 +157,8 @@ public class XMPPError extends AbstractError {
      * 
      * @param type the error type.
      * @param condition the error condition.
+     * @param conditionText
+     * @param errorGenerator
      * @param descriptiveTexts 
      * @param extensions list of stanza(/packet) extensions
      * @param stanza the stanza carrying this XMPP error.

smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java

@@ -236,11 +236,10 @@ public abstract class SASLMechanism implements Comparable<SASLMechanism> {
      *
      * @param challengeString a base64 encoded string representing the challenge.
      * @param finalChallenge true if this is the last challenge send by the server within the success stanza
-     * @throws NotConnectedException
-     * @throws SmackException
-     * @throws InterruptedException 
+     * @throws SmackException exception
+     * @throws InterruptedException if the connection is interrupted
      */
-    public final void challengeReceived(String challengeString, boolean finalChallenge) throws SmackException, NotConnectedException, InterruptedException {
+    public final void challengeReceived(String challengeString, boolean finalChallenge) throws SmackException, InterruptedException {
         byte[] challenge = Base64.decode((challengeString != null && challengeString.equals("=")) ? "" : challengeString);
         byte[] response = evaluateChallenge(challenge);
         if (finalChallenge) {
@@ -260,7 +259,12 @@ public abstract class SASLMechanism implements Comparable<SASLMechanism> {
     }
 
     /**
-     * @throws SmackException
+     * Evaluate the SASL challenge.
+     *
+     * @param challenge challenge to evaluate.
+     *
+     * @return null.
+     * @throws SmackException in case of an error.
      */
     protected byte[] evaluateChallenge(byte[] challenge) throws SmackException {
         return null;

smack-core/src/main/java/org/jivesoftware/smack/util/DNSUtil.java

@@ -127,6 +127,7 @@ public class DNSUtil {
      *
      * @param domain the domain.
      * @param failedAddresses on optional list that will be populated with host addresses that failed to resolve.
+     * @param dnssecMode DNSSec mode.
      * @return List of HostAddress, which encompasses the hostname and port that the
      *      XMPP server can be reached at for the specified domain.
      */
@@ -147,6 +148,7 @@ public class DNSUtil {
      *
      * @param domain the domain.
      * @param failedAddresses on optional list that will be populated with host addresses that failed to resolve.
+     * @param dnssecMode DNSSec mode.
      * @return List of HostAddress, which encompasses the hostname and port that the
      *      XMPP server can be reached at for the specified domain.
      */

smack-core/src/main/java/org/jivesoftware/smack/util/FileUtils.java

@@ -104,7 +104,7 @@ public final class FileUtils {
      * @throws IOException 
      */
     @SuppressWarnings("DefaultCharset")
-    public static String readFileOrThrow(File file) throws FileNotFoundException, IOException {
+    public static String readFileOrThrow(File file) throws IOException {
         Reader reader = null;
         try {
             reader = new FileReader(file);

smack-core/src/main/java/org/jivesoftware/smack/util/PacketParserUtils.java

@@ -709,6 +709,7 @@ public class PacketParserUtils {
      *
      * @param parser the XML parser, positioned at the start of the compression stanza.
      * @return The CompressionFeature stream element
+     * @throws IOException
      * @throws XmlPullParserException if an exception occurs while parsing the stanza.
      */
     public static Compress.Feature parseCompressionFeature(XmlPullParser parser)
@@ -716,7 +717,7 @@ public class PacketParserUtils {
         assert (parser.getEventType() == XmlPullParser.START_TAG);
         String name;
         final int initialDepth = parser.getDepth();
-        List<String> methods = new LinkedList<String>();
+        List<String> methods = new LinkedList<>();
         outerloop: while (true) {
             int eventType = parser.next();
             switch (eventType) {
@@ -899,7 +900,14 @@ public class PacketParserUtils {
     }
 
     /**
-     * Parse an extension element.
+     * Parses an extension element.
+     *
+     * @param elementName the XML element name of the extension element.
+     * @param namespace the XML namespace of the stanza(/packet) extension.
+     * @param parser the XML parser, positioned at the starting element of the extension.
+     *
+     * @return an extension element.
+     * @throws Exception when an error occurs during parsing.
      * @deprecated use {@link #parseExtensionElement(String, String, XmlPullParser)} instead.
      */
     @Deprecated
@@ -914,7 +922,9 @@ public class PacketParserUtils {
      * @param elementName the XML element name of the extension element.
      * @param namespace the XML namespace of the stanza(/packet) extension.
      * @param parser the XML parser, positioned at the starting element of the extension.
+     *
      * @return an extension element.
+     * @throws Exception when an error occurs during parsing.
      */
     public static ExtensionElement parseExtensionElement(String elementName, String namespace,
                     XmlPullParser parser) throws Exception {

smack-core/src/main/java/org/jivesoftware/smack/util/PacketUtil.java

@@ -25,9 +25,11 @@ public class PacketUtil {
     /**
      * Get a extension element from a collection.
      *
-     * @param collection
-     * @param element
-     * @param namespace
+     * @param collection Collection of ExtensionElements.
+     * @param element name of the targeted ExtensionElement.
+     * @param namespace namespace of the targeted ExtensionElement.
+     * @param <PE> Type of the ExtensionElement
+     *
      * @return the extension element
      * @deprecated use {@link #extensionElementFrom(Collection, String, String)} instead
      */
@@ -41,9 +43,11 @@ public class PacketUtil {
     /**
      * Get a extension element from a collection.
      *
-     * @param collection
-     * @param element
-     * @param namespace
+     * @param collection Collection of ExtensionElements.
+     * @param element name of the targeted ExtensionElement.
+     * @param namespace namespace of the targeted ExtensionElement.
+     * @param <PE> Type of the ExtensionElement
+     *
      * @return the extension element
      */
     @SuppressWarnings("unchecked")

smack-core/src/main/java/org/jivesoftware/smack/util/TLSUtils.java

@@ -60,6 +60,9 @@ public class TLSUtils {
      * </p>
      * 
      * @param builder the configuration builder to apply this setting to
+     * @param <B> Type of the ConnectionConfiguration builder.
+     *
+     * @return the given builder
      */
     public static <B extends ConnectionConfiguration.Builder<B,?>> B setTLSOnly(B builder) {
         builder.setEnabledSSLProtocols(new String[] { PROTO_TLSV1_2,  PROTO_TLSV1_1, PROTO_TLSV1 });
@@ -77,6 +80,9 @@ public class TLSUtils {
      * </p>
      * 
      * @param builder the configuration builder to apply this setting to
+     * @param <B> Type of the ConnectionConfiguration builder.
+     *
+     * @return the given builder
      */
     public static <B extends ConnectionConfiguration.Builder<B,?>> B setSSLv3AndTLSOnly(B builder) {
         builder.setEnabledSSLProtocols(new String[] { PROTO_TLSV1_2,  PROTO_TLSV1_1, PROTO_TLSV1, PROTO_SSL3 });
@@ -92,6 +98,7 @@ public class TLSUtils {
      * </p>
      * 
      * @param builder a connection configuration builder.
+     * @param <B> Type of the ConnectionConfiguration builder.
      * @throws NoSuchAlgorithmException
      * @throws KeyManagementException
      * @return the given builder.
@@ -120,6 +127,7 @@ public class TLSUtils {
      * </p>
      * 
      * @param builder a connection configuration builder.
+     * @param <B> Type of the ConnectionConfiguration builder.
      * @return the given builder.
      */
     public static <B extends ConnectionConfiguration.Builder<B,?>> B disableHostnameVerificationForTlsCertificates(B builder) {

smack-core/src/main/java/org/jivesoftware/smack/util/dns/DNSResolver.java

@@ -42,6 +42,8 @@ public abstract class DNSResolver {
     /**
      * Gets a list of service records for the specified service.
      * @param name The symbolic name of the service.
+     * @param failedAddresses list of failed addresses.
+     * @param dnssecMode security mode.
      * @return The list of SRV records mapped to the service name.
      */
     public final List<SRVRecord> lookupSRVRecords(String name, List<HostAddress> failedAddresses, DnssecMode dnssecMode) {

smack-core/src/main/java/org/jivesoftware/smack/util/dns/HostAddress.java

@@ -38,6 +38,7 @@ public class HostAddress {
      * 
      * @param fqdn the optional fully qualified domain name (FQDN).
      * @param port The port to connect on.
+     * @param inetAddresses list of addresses.
      * @throws IllegalArgumentException If the port is out of valid range (0 - 65535).
      */
     public HostAddress(String fqdn, int port, List<InetAddress> inetAddresses) {

smack-core/src/main/java/org/jivesoftware/smack/util/dns/SRVRecord.java

@@ -41,6 +41,7 @@ public class SRVRecord extends HostAddress implements Comparable<SRVRecord> {
      * @param port The connection port
      * @param priority Priority of the target host
      * @param weight Relative weight for records with same priority
+     * @param inetAddresses list of addresses.
      * @throws IllegalArgumentException fqdn is null or any other field is not in valid range (0-65535).
      */
     public SRVRecord(String fqdn, int port, int priority, int weight, List<InetAddress> inetAddresses) {