Updating Javadoc to be compatible with the new Java 8 JRE (#285)

* Testing Travis issue with OfflineBufferingTest.testManyMessageBufferAndDeliver

Signed-off-by: James Sutton <james.sutton@uk.ibm.com>

* Removing accidential test log entry

Signed-off-by: James Sutton <james.sutton@uk.ibm.com>

* Fixing Javadoc to be Java 8 compliant

Signed-off-by: James Sutton <james.sutton@uk.ibm.com>

Author: jpwsutton

org.eclipse.paho.client.mqttv3/pom.xml

@@ -11,6 +11,7 @@
 	<packaging>eclipse-plugin</packaging>
 
 	<profiles>
+	<!-- 
 		<profile>
 			<id>doclint-java8-disable</id>
 	    		<activation>
@@ -20,6 +21,7 @@
 				<javadoc.opts>-Xdoclint:none</javadoc.opts>
 			</properties>
 		</profile>
+		 -->
 	</profiles>
 
 	<build>
@@ -77,7 +79,7 @@
 					<target>${mqttclient.java.version}</target>
 				</configuration>
 			</plugin>
-			<!-- <plugin>
+			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
 				<version>2.10.3</version>
@@ -93,7 +95,7 @@
 					</execution>
 				</executions>
 			</plugin>
-			<plugin>
+			<!-- <plugin>
 				<groupId>org.eclipse.tycho.extras</groupId>
 				<artifactId>tycho-document-bundle-plugin</artifactId>
 		        <executions>

org.eclipse.paho.client.mqttv3/src/main/java-templates/org/eclipse/paho/client/mqttv3/internal/ClientComms.java

@@ -84,6 +84,10 @@ public class ClientComms {
 	/**
 	 * Creates a new ClientComms object, using the specified module to handle
 	 * the network calls.
+	 * @param client The {@link IMqttAsyncClient}
+	 * @param persistence the {@link MqttClientPersistence} layer.
+	 * @param pingSender the {@link MqttPingSender}
+	 * @throws MqttException if an exception occurs whilst communicating with the server
 	 */
 	public ClientComms(IMqttAsyncClient client, MqttClientPersistence persistence, MqttPingSender pingSender) throws MqttException {
 		this.conState = DISCONNECTED;
@@ -141,6 +145,9 @@ void internalSend(MqttWireMessage message, MqttToken token) throws MqttException
 	/**
 	 * Sends a message to the broker if in connected state, but only waits for the message to be
 	 * stored, before returning.
+	 * @param message The {@link MqttWireMessage} to send
+	 * @param token The {@link MqttToken} to send.
+	 * @throws MqttException if an error occurs sending the message
 	 */
 	public void sendNoWait(MqttWireMessage message, MqttToken token) throws MqttException {
 		final String methodName = "sendNoWait";
@@ -218,6 +225,9 @@ public void close() throws MqttException {
 	 * Sends a connect message and waits for an ACK or NACK.
 	 * Connecting is a special case which will also start up the
 	 * network connection, receive thread, and keep alive thread.
+	 * @param options The {@link MqttConnectOptions} for the connection
+	 * @param token The {@link MqttToken} to track the connection
+	 * @throws MqttException if an error occurs when connecting
 	 */
 	public void connect(MqttConnectOptions options, MqttToken token) throws MqttException {
 		final String methodName = "connect";
@@ -288,6 +298,8 @@ public void connectComplete( MqttConnack cack, MqttException mex) throws MqttExc
 	 * an abnormal disconnection.  The method may be invoked multiple times
 	 * in parallel as each thread when it receives an error uses this method
 	 * to ensure that shutdown completes successfully.
+	 * @param token the {@link MqttToken} To track closing the connection
+	 * @param reason the {@link MqttException} thrown requiring the connection to be shut down.
 	 */
 	public void shutdownConnection(MqttToken token, MqttException reason) {
 		final String methodName = "shutdownConnection";
@@ -478,6 +490,10 @@ public void disconnectForcibly(long quiesceTimeout, long disconnectTimeout) thro
 
 	/**
 	 * Disconnect the connection and reset all the states.
+	 * @param quiesceTimeout How long to wait whilst quiesing before messages are deleted.
+	 * @param disconnectTimeout How long to wait whilst disconnecting
+	 * @param sendDisconnectPacket If true, will send a disconnect packet
+	 * @throws MqttException if an error occurs whilst disconnecting
 	 */
 	public void disconnectForcibly(long quiesceTimeout, long disconnectTimeout, boolean sendDisconnectPacket) throws MqttException {
 		// Allow current inbound and outbound work to complete
@@ -765,7 +781,7 @@ private void handleRunException(Exception ex) {
 	/**
 	 * When Automatic reconnect is enabled, we want ClientComs to enter the
 	 * 'resting' state if disconnected. This will allow us to publish messages
-	 * @param resting
+	 * @param resting if true, resting is enabled
 	 */
 	public void setRestingState(boolean resting) {
 		this.resting = resting;
@@ -792,7 +808,6 @@ public void deleteBufferedMessage(int bufferIndex){
 	/**
 	 * When the client automatically reconnects, we want to send all messages from the
 	 * buffer first before allowing the user to send any messages
-	 * @throws MqttException 
 	 */
 	public void notifyReconnect() {
 		final String methodName = "notifyReconnect";

org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/IMqttActionListener.java

@@ -24,6 +24,7 @@ public interface IMqttActionListener {
 	 * are in the process of being delivered will be delivered to the requested
 	 * quality of service next time the client connects.  
 	 * @param asyncActionToken associated with the action that has failed
+	 * @param exception thrown by the action that has failed
 	 */
 	public void onFailure(IMqttToken asyncActionToken, Throwable exception);
 }

org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/IMqttAsyncClient.java

@@ -24,16 +24,16 @@
  * <p>
  * It provides applications a simple programming interface to all features of the MQTT version 3.1
  * specification including:
+ * </p>
  * <ul>
  * <li>connect
  * <li>publish
  * <li>subscribe
  * <li>unsubscribe
  * <li>disconnect
  * </ul>
- * </p>
  * <p>
- * There are two styles of MQTT client, this one and {@link IMqttClient}.
+ * There are two styles of MQTT client, this one and {@link IMqttClient}.</p>
  * <ul>
  * <li>IMqttAsyncClient provides a set of non-blocking methods that return control to the
  * invoking application after initial validation of parameters and state. The main processing is
@@ -51,7 +51,6 @@
  * versions of the MQTT client. In most circumstances it is recommended to use IMqttAsyncClient
  * based clients which allow an application to mix both non-blocking and blocking calls. </li>
  * </ul>
- * </p>
  * <p>
  * An application is not restricted to using one style if an IMqttAsyncClient based client is used
  * as both blocking and non-blocking methods can be used in the same application. If an IMqttClient
@@ -61,40 +60,38 @@
  * <p>There are two forms of non-blocking method:
  * <ol>
  *   <li>
- *     <code><pre>
+ *     <pre>
  *     IMqttToken token = asyncClient.method(parms)
- *     </pre></code>
+ *     </pre>
  *     <p>In this form the method returns a token that can be used to track the
  *     progress of the action (method). The method provides a waitForCompletion()
  *     method that once invoked will block until the action completes. Once
  *     completed there are method on the token that can be used to check if the
  *     action completed successfully or not. For example
- * 	   to wait until a connect completes:
- *     <code><pre>
+ * 	   to wait until a connect completes:</p>
+ *     <pre>
  *      IMqttToken conToken;
  *   	conToken = asyncClient.client.connect(conToken);
  *     ... do some work...
  *   	conToken.waitForCompletion();
- *     </pre></code>
- *	   </p>
- *     <p>To turn a method into a blocking invocation the following form can be used:
- *     <code><pre>
+ *     </pre>
+ *     <p>To turn a method into a blocking invocation the following form can be used:</p>
+ *     <pre>
  *     IMqttToken token;
  *     token = asyncClient.method(parms).waitForCompletion();
- *     </pre></code>
-
+ *     </pre>
  *   </li>
  *
  *   <li>
- *     <code><pre>
+ *     <pre>
  *     IMqttToken token method(parms, Object userContext, IMqttActionListener callback)
- *     </pre></code>
+ *     </pre>
  *     <p>In this form a callback is registered with the method. The callback will be
  *     notified when the action succeeds or fails. The callback is invoked on the thread
  *     managed by the MQTT client so it is important that processing is minimised in the
  *     callback. If not the operation of the MQTT client will be inhibited. For example
- *     to be notified (called back) when a connect completes:
- *     <code><pre>
+ *     to be notified (called back) when a connect completes:</p>
+ *     <pre>
  *     	IMqttToken conToken;
  *	    conToken = asyncClient.connect("some context",new new MqttAsyncActionListener() {
  *			public void onSuccess(IMqttToken asyncActionToken) {
@@ -105,8 +102,8 @@
  *				log ("connect failed" +exception);
  *			}
  *		  });
- *      </pre></code>
- *	    An optional context object can be passed into the method which will then be made
+ *      </pre>
+ *	    <p>An optional context object can be passed into the method which will then be made
  *      available in the callback. The context is stored by the MQTT client) in the token
  *      which is then returned to the invoker. The token is provided to the callback methods
  *      where the context can then be accessed.
@@ -174,11 +171,11 @@ public interface IMqttAsyncClient {
 	 * </p>
 	 * <p>The method returns control before the connect completes. Completion can
 	 * be tracked by:
+	 * </p>
 	 * <ul>
 	 * <li>Waiting on the returned token {@link IMqttToken#waitForCompletion()} or</li>
 	 * <li>Passing in a callback {@link IMqttActionListener}</li>
 	 * </ul>
-	 * </p>
 	 *
 	 * @param options a set of connection parameters that override the defaults.
 	 * @param userContext optional object for used to pass context to the callback. Use
@@ -259,11 +256,11 @@ public interface IMqttAsyncClient {
 	 * <p>This method must not be called from inside {@link MqttCallback} methods.</p>
 	 * <p>The method returns control before the disconnect completes. Completion can
 	 * be tracked by:
+	 * </p>
 	 * <ul>
 	 * <li>Waiting on the returned token {@link IMqttToken#waitForCompletion()} or</li>
 	 * <li>Passing in a callback {@link IMqttActionListener}</li>
 	 * </ul>
-	 * </p>
 	 *
 	 * @param quiesceTimeout the amount of time in milliseconds to allow for
 	 * existing work to finish before disconnecting.  A value of zero or less
@@ -419,6 +416,7 @@ public IMqttDeliveryToken publish(String topic, byte[] payload, int qos,
 	 * client and will be delivered on a background thread.
 	 * In the event the connection fails or the client stops. Messages will be delivered to the
 	 * requested quality of service once the connection is re-established to the server on condition that:
+	 * </p>
 	 * <ul>
 	 * <li>The connection is re-established with the same clientID
 	 * <li>The original connection was made with (@link MqttConnectOptions#setCleanSession(boolean)}
@@ -427,7 +425,6 @@ public IMqttDeliveryToken publish(String topic, byte[] payload, int qos,
 	 * set to false
 	 * <li>Depending when the failure occurs QoS 0 messages may not be delivered.
 	 * </ul>
-	 * </p>
 	 *
 	 * <p>When building an application,
 	 * the design of the topic tree should take into account the following principles
@@ -442,30 +439,29 @@ public IMqttDeliveryToken publish(String topic, byte[] payload, int qos,
 	 * 	<li>A leading "/" creates a distinct topic.  For example, <em>/finance</em> is
 	 * 	different from <em>finance</em>. <em>/finance</em> matches "+/+" and "/+", but
 	 * 	not "+".</li>
-	 * 	<li>Do not include the null character (Unicode <samp class="codeph">\x0000</samp>) in
+	 * 	<li>Do not include the null character (Unicode <pre>\x0000</pre>) in
 	 * 	any topic.</li>
 	 * </ul>
 	 *
 	 * <p>The following principles apply to the construction and content of a topic
 	 * tree:</p>
-	 *
 	 * <ul>
 	 * 	<li>The length is limited to 64k but within that there are no limits to the
 	 * 	number of levels in a topic tree.</li>
 	 * 	<li>There can be any number of root nodes; that is, there can be any number
 	 * 	of topic trees.</li>
 	 * 	</ul>
-	 * </p>
+	 * 
 	 * <p>The method returns control before the publish completes. Completion can
 	 * be tracked by:
+	 * </p>
 	 * <ul>
 	 * <li>Setting an {@link IMqttAsyncClient#setCallback(MqttCallback)} where the
 	 * {@link MqttCallback#deliveryComplete(IMqttDeliveryToken)}
 	 * method will be called.</li>
 	 * <li>Waiting on the returned token {@link MqttToken#waitForCompletion()} or</li>
 	 * <li>Passing in a callback {@link IMqttActionListener} to this method</li>
 	 * </ul>
-	 * </p>
 	 *
 	 * @param topic  to deliver the message to, for example "finance/stock/ibm".
 	 * @param message to deliver to the server
@@ -551,23 +547,25 @@ public IMqttToken subscribe(String topicFilter, int qos, Object userContext, IMq
 	 * <p>
 	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true
 	 * when when connecting to the server then the subscription remains in place
-	 * until either:
+	 * until either:</p>
+	 * 
 	 * <ul>
 	 * <li>The client disconnects</li>
 	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
-	 * </li>
-	 * </p>
+	 * </ul>
+	 * 
 	 * <p>
 	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false
 	 * when connecting to the server then the subscription remains in place
-	 * until either:
+	 * until either:</p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The next time the client connects with cleanSession set to true</ul>
-	 * </li>
+	 * <li>The next time the client connects with cleanSession set to true</li>
+	 * </ul>
+	 * <p>
 	 * With cleanSession set to false the MQTT server will store messages on
 	 * behalf of the client when the client is not connected. The next time the
-	 * client connects with the <bold>same client ID</bold> the server will
+	 * client connects with the <b>same client ID</b> the server will
 	 * deliver the stored messages to the client.
 	 * </p>
 	 *
@@ -589,9 +587,12 @@ public IMqttToken subscribe(String topicFilter, int qos, Object userContext, IMq
 	 * 	<dd><p>The number sign (#) is a wildcard character that matches
 	 * 	any number of levels within a topic. For example, if you subscribe to
 	 *  <span><span class="filepath">finance/stock/ibm/#</span></span>, you receive
-	 * 	messages on these topics:
-	 *  <pre>   finance/stock/ibm<br />   finance/stock/ibm/closingprice<br />   finance/stock/ibm/currentprice</pre>
-	 *  </p>
+	 * 	messages on these topics:</p>
+	 *  <ul>
+	 *  <li>finance/stock/ibm</li>
+	 *  <li>finance/stock/ibm/closingprice</li>
+	 *  <li>finance/stock/ibm/currentprice</li>
+	 *  </ul>
 	 *  <p>The multi-level wildcard
 	 *  can represent zero or more levels. Therefore, <em>finance/#</em> can also match
 	 * 	the singular <em>finance</em>, where <em>#</em> represents zero levels. The topic
@@ -622,14 +623,12 @@ public IMqttToken subscribe(String topicFilter, int qos, Object userContext, IMq
 	 * 	For example, <em>finance/+</em> and <em>finance/+/ibm</em> are both valid.</span></p>
 	 * 	</dd>
 	 * </dl>
-	 * </p>
 	 * <p>The method returns control before the subscribe completes. Completion can
-	 * be tracked by:
+	 * be tracked by:</p>
 	 * <ul>
 	 * <li>Waiting on the supplied token {@link MqttToken#waitForCompletion()} or</li>
 	 * <li>Passing in a callback {@link IMqttActionListener} to this method</li>
 	 * </ul>
-	 * </p>
 	 *
 	 * @param topicFilters one or more topics to subscribe to, which can include wildcards
 	 * @param qos the maximum quality of service to subscribe each topic at.Messages
@@ -790,11 +789,12 @@ public IMqttToken unsubscribe(String topicFilter, Object userContext, IMqttActio
 	 * </p>
 	 * <p>The method returns control before the unsubscribe completes. Completion can
 	 * be tracked by:
+	 * </p>
+	 * 
 	 * <ul>
 	 * <li>Waiting on the returned token {@link MqttToken#waitForCompletion()} or</li>
 	 * <li>Passing in a callback {@link IMqttActionListener} to this method</li>
 	 * </ul>
-	 * </p>
 	 *
 	 * @param topicFilters one or more topics to unsubscribe from. Each topicFilter
 	 * must match one specified on an earlier subscribe.
@@ -814,12 +814,12 @@ public IMqttToken unsubscribe(String[] topicFilters, Object userContext, IMqttAc
 	 * Sets a callback listener to use for events that happen asynchronously.
 	 * <p>There are a number of events that the listener will be notified about.
 	 * These include:
+	 * </p>
 	 * <ul>
 	 * <li>A new message has arrived and is ready to be processed</li>
 	 * <li>The connection to the server has been lost</li>
 	 * <li>Delivery of a message to the server has completed</li>
 	 * </ul>
-	 * </p>
 	 * <p>Other events that track the progress of an individual operation such
 	 * as connect and subscribe can be tracked using the {@link MqttToken} returned from
 	 * each non-blocking method or using setting a {@link IMqttActionListener} on the
@@ -852,7 +852,7 @@ public IMqttToken unsubscribe(String[] topicFilters, Object userContext, IMqttAc
 	 * sent.  The default behaviour, when manualAcks is false, is to send the MQTT
 	 * acknowledgements automatically at the successful completion of the messageArrived
 	 * callback method.
-	 * @param manualAcks
+	 * @param manualAcks if set to true MQTT acknowledgements are not sent
 	 */
 	public void setManualAcks(boolean manualAcks);
 
@@ -861,7 +861,7 @@ public IMqttToken unsubscribe(String[] topicFilters, Object userContext, IMqttAc
 	 * This will cause the MQTT acknowledgement to be sent to the server.
 	 * @param messageId the MQTT message id to be acknowledged
 	 * @param qos the MQTT QoS of the message to be acknowledged
-	 * @throws MqttException
+	 * @throws MqttException if there was a problem sending the acknowledgement
 	 */
 	public void messageArrivedComplete(int messageId, int qos) throws MqttException;