Fixed errors in javadoc generation as suggested by doclint.

Author: nicolaiparlog

src/main/java/org/codefx/libfx/concurrent/when/ExecuteWhen.java

@@ -8,15 +8,16 @@
 import javafx.beans.value.ObservableValue;
 
 /**
- * Builder for {@link ExecuteAlwaysWhen} and {@link ExecuteOnceWhen}.
  * <p>
+ * Builder for {@link ExecuteAlwaysWhen} and {@link ExecuteOnceWhen}.
+ * </p>
  * <h2>Example</h2>A typical use would look like this:
  *
  * <pre>
- * 	ObservableValue<State> workerState;
+ * 	ObservableValue&lt;State&gt; workerState;
  *	ExecuteWhen.on(workerState)
- *		.when(state -> state == State.SUCCEEDED)
- *		.thenOnce(state -> logSuccess())
+ *		.when(state -&gt; state == State.SUCCEEDED)
+ *		.thenOnce(state -&gt; logSuccess())
  *		.executeWhen();
  * </pre>
  *

src/main/java/org/codefx/libfx/control/properties/ControlPropertyListenerBuilder.java

@@ -18,11 +18,13 @@
  * it to check the type of the value before casting it to the type accepted by the value processor. If those types do
  * not match, this prevents {@link ClassCastException} (which would otherwise be caught and silently ignored). If that
  * case occurs frequently, specifying the type to allow the check will improve performance considerably.
+ * </p>
+ * <h2>Example</h2>
  * <p>
  * A typical use looks like this:
  *
  * <pre>
- * ControlProperties.<Boolean> on(control.getProperties())
+ * ControlProperties.&lt;Boolean&gt; on(control.getProperties())
  * 	.forKey("visible")
  * 	.processValue(this::setVisibility)
  * 	.buildDetached();

src/main/java/org/codefx/libfx/control/properties/ControlPropertyListenerHandle.java

@@ -3,10 +3,13 @@
 import org.codefx.libfx.listener.handle.ListenerHandle;
 
 /**
+ * <p>
  * This is a {@link ListenerHandle handle} on a {@code ControlPropertyListener}, which can be used to {@link #attach()}
  * and {@link #detach()} it. The {@code ControlPropertyListener} is no type on its own so it is described here.
+ * </p>
+ * <h2>ControlPropertyListener</h2>
  * <p>
- * <h2>ControlPropertyListener</h2> A control property listener listens to the changes in a Control's
+ * A control property listener listens to the changes in a Control's
  * {@link javafx.scene.control.Control#getProperties() propertyMap}. It is created to listen for a specific key and
  * hands all new values for that key to a value processor (a {@link java.util.function.Consumer Consumer})..
  * <p>
@@ -15,10 +18,12 @@
  * <p>
  * Regardless of whether a value could be cast and processed or not, it will be removed from the map. So if the same
  * value is set repeatedly, the specified value processor is called every time.
+ * </p>
+ * <h2>ControlPropertyListenerHandle</h2>
  * <p>
- * <h2>ControlPropertyListenerHandle</h2> Listener handles are not thread-safe. See {@link ListenerHandle} for details.
- * Additionally, a new value might be processed twice if inserted into a map by another thread while {@link #attach()}
- * is executed. This behavior should not be relied upon and might change (i.e. be fixed) in the future.
+ * Listener handles are not thread-safe. See {@link ListenerHandle} for details. Additionally, a new value might be
+ * processed twice if inserted into a map by another thread while {@link #attach()} is executed. This behavior should
+ * not be relied upon and might change (i.e. be fixed) in the future.
  * <p>
  * A listener handle is best created with the {@link ControlPropertyListenerBuilder}.
  */

src/main/java/org/codefx/libfx/control/properties/package-info.java

@@ -3,9 +3,10 @@
  * This package provides functionality to make using a {@link javafx.scene.control.Control Control}'s
  * {@link javafx.scene.control.Control#getProperties() propertyMap} easier. As such its main use will be to creators of
  * controls.
+ * </p>
+ * <h2>Listening to the Property Map</h2>
  * <p>
- * <h2>Listening to the Property Map</h2> In order to use the property map, a control has to create a listener which
- * does these things:
+ * In order to use the property map, a control has to create a listener which does these things:
  * <ul>
  * <li>identify the correct key
  * <li>check whether the value is of the correct type and cast it
@@ -14,14 +15,15 @@
  * </ul>
  * While implementing such a listener is not difficult, some details have to be considered. This makes the code a little
  * lengthy and hinders readability while at the same time repeating the same pattern over and over.
+ * <h2>ControlPropertyListener</h2>
  * <p>
- * <h2>ControlPropertyListener</h2> This package provides usability functions to create such a listener in a concise and
- * readable way (this code would be inside a control):
+ * This package provides usability functions to create such a listener in a concise and readable way (this code would be
+ * inside a control):
  *
  * <pre>
  * ControlProperties.on(getProperties())
  * 	.forKey("SomeKey")
- * 	.processValue(valueString -> System.out.println(valueString))
+ * 	.processValue(valueString -&gt; System.out.println(valueString))
  * 	.buildAndAttach();
  * </pre>
  * It returns an instance of {@link org.codefx.libfx.control.properties.ControlPropertyListenerHandle

src/main/java/org/codefx/libfx/control/webview/WebViews.java

@@ -42,7 +42,7 @@ private WebViews() {
 	 * @param listener
 	 *            the {@link WebViewHyperlinkListener} to add to the web view
 	 * @return a handle on the created listener which allows to attach and detach it; initially detached
-	 * @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener)
+	 * @see #addHyperlinkListener(WebView, WebViewHyperlinkListener)
 	 */
 	public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 			WebView webView, WebViewHyperlinkListener listener) {
@@ -65,7 +65,7 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 	 * @param eventType
 	 *            the {@link EventType} of all events passed to the listener
 	 * @return a handle on the created listener which allows to attach and detach it; initially detached
-	 * @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener, EventType)
+	 * @see #addHyperlinkListener(WebView, WebViewHyperlinkListener, HyperlinkEvent.EventType)
 	 */
 	public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 			WebView webView, WebViewHyperlinkListener listener, EventType eventType) {
@@ -97,8 +97,8 @@ public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 	}
 
 	/**
-	 * {@link #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, EventType) Creates} a listener handle
-	 * and immediately {@link WebViewHyperlinkListenerHandle#attach() attaches} it.
+	 * {@link #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, HyperlinkEvent.EventType) Creates} a
+	 * listener handle and immediately {@link WebViewHyperlinkListenerHandle#attach() attaches} it.
 	 *
 	 * @param webView
 	 *            the {@link WebView} to which the listener will be added
@@ -107,7 +107,7 @@ public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 	 * @param eventType
 	 *            the {@link EventType} of all events passed to the listener
 	 * @return a handle on the created listener which allows to attach and detach it; initially attached
-	 * @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, EventType)
+	 * @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, HyperlinkEvent.EventType)
 	 */
 	public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 			WebView webView, WebViewHyperlinkListener listener, EventType eventType) {

src/main/java/org/codefx/libfx/control/webview/package-info.java

@@ -1,8 +1,11 @@
 /**
+ * <p>
  * This package provides functionality around JavaFX' {@link javafx.scene.web.WebView WebView}. All of it can be
  * accessed via the utility class {@link org.codefx.libfx.control.webview.WebViews WebViews}.
+ * </p>
+ * <h2>Hyperlink Listener</h2>
  * <p>
- * <h2>Hyperlink Listener</h2> The {@code WebView} provides no pleasant way to add an equivalent of Swing's
+ * The {@code WebView} provides no pleasant way to add an equivalent of Swing's
  * {@link javax.swing.event.HyperlinkListener HyperlinkListener}.
  * <p>
  * This can now be done by implementing a {@link org.codefx.libfx.control.webview.WebViewHyperlinkListener

src/main/java/org/codefx/libfx/dom/StaticDomEventConverter.java

@@ -3,6 +3,7 @@
 import java.util.Objects;
 
 import javax.swing.event.HyperlinkEvent;
+import javax.swing.event.HyperlinkEvent.EventType;
 
 import org.w3c.dom.events.Event;
 
@@ -15,9 +16,13 @@
 public final class StaticDomEventConverter {
 
 	/**
+	 * Indicates whether the specified DOM event can be converted to a {@link HyperlinkEvent}.
+	 *
+	 * @param domEvent
+	 *            the DOM-{@link Event}
+	 * @return true if the event's {@link Event#getType() type} has an equivalent {@link EventType EventType}
 	 * @see DomEventConverter#canConvertToHyperlinkEvent(Event)
 	 */
-	@SuppressWarnings("javadoc")
 	public static boolean canConvertToHyperlinkEvent(Event domEvent) {
 		Objects.requireNonNull(domEvent, "The argument 'domEvent' must not be null.");
 
@@ -27,9 +32,29 @@ public static boolean canConvertToHyperlinkEvent(Event domEvent) {
 	}
 
 	/**
+	 * Converts the specified DOM event to a hyperlink event.
+	 *
+	 * @param domEvent
+	 *            the DOM-{@link Event} from which the {@link HyperlinkEvent} will be created
+	 * @param source
+	 *            the source of the {@code domEvent}
+	 * @return a {@link HyperlinkEvent} with the following properties:
+	 *         <ul>
+	 *         <li> {@link HyperlinkEvent#getEventType() getEventType()} returns the {@link EventType} corresponding to
+	 *         the domEvent's type as defined by {@link DomEventType}
+	 *         <li> {@link HyperlinkEvent#getSource() getSource()} returns the specified {@code source}
+	 *         <li> {@link HyperlinkEvent#getURL() getUrl()} returns the href-attribute's value of the event's source
+	 *         element
+	 *         <li> {@link HyperlinkEvent#getDescription() getDescription()} returns the text content of the event's
+	 *         source element
+	 *         <li> {@link HyperlinkEvent#getInputEvent() getInputEvent()} returns null
+	 *         <li> {@link HyperlinkEvent#getSourceElement() getSourceElement()} returns null
+	 *         </ul>
+	 * @throws IllegalArgumentException
+	 *             if the specified event can not be converted to a hyperlink event; this is the case if
+	 *             {@link #canConvertToHyperlinkEvent(Event)} returns false
 	 * @see DomEventConverter#convertToHyperlinkEvent(Event, Object)
 	 */
-	@SuppressWarnings("javadoc")
 	public static HyperlinkEvent convertToHyperlinkEvent(Event domEvent, Object source)
 			throws IllegalArgumentException {
 

src/main/java/org/codefx/libfx/dom/package-info.java

@@ -1,6 +1,7 @@
 /**
- * This package provides functionality around DOM, i.e. classes from {@code org.w3c.dom}.
  * <p>
+ * This package provides functionality around DOM, i.e. classes from {@code org.w3c.dom}.
+ * </p>
  * <h2>Event Conversion</h2> The class {@link org.codefx.libfx.dom.DomEventConverter DomEventConverter} defines methods
  * which allow the conversion of {@link org.w3c.dom.events.Event DOM Events} to {@link javax.swing.event.HyperlinkEvent
  * HyperlinkEvents}. {@link org.codefx.libfx.dom.StaticDomEventConverter StaticDomEventConverter} gives access to the

src/main/java/org/codefx/libfx/listener/handle/ListenerHandleBuilder.java

@@ -19,17 +19,19 @@
  * <p>
  * The {@link ListenerHandle} returned by this builder is not yet attached, i.e. it does not initially call the
  * functions given to {@code onAttach} or {@code onDetach}.
+ * </p>
+ * <h2>Example</h2>
  * <p>
- * <h2>Example</h2> A typical use looks like this:
+ * A typical use looks like this:
  *
  * <pre>
- * Property<String> textProperty;
- * ChangeListener<String> textListener;
+ * Property&lt;String&gt; textProperty;
+ * ChangeListener&lt;String&gt; textListener;
  *
  * ListenerHandle textListenerHandle = ListenerHandleBuilder
  * 	.from(textProperty, textListener)
- * 	.onAttach((property, listener) -> property.addListener(listener))
- * 	.onDetach((property, listener) -> property.removeListener(listener))
+ * 	.onAttach((property, listener) -&gt; property.addListener(listener))
+ * 	.onDetach((property, listener) -&gt; property.removeListener(listener))
  * 	.build();
  * </pre>
  *

src/main/java/org/codefx/libfx/serialization/SerializableOptional.java

@@ -18,15 +18,16 @@
  * The class can be used as an argument or return type for serialization-based RPC technologies like RMI.
  * <p>
  * There are three ways to use this class to serialize instances which have an optional field.
+ * </p>
+ * <h2>Transform On Serialization</h2>
  * <p>
- * <h2>Transform On Serialization</h2> The field can be declared as {@code transient Optional<T> optionalField}, which
- * will exclude it from serialization.
+ * The field can be declared as {@code transient Optional<T> optionalField}, which will exclude it from serialization.
  * <p>
  * The class then needs to implement custom (de)serialization methods {@code writeObject} and {@code readObject}. They
  * must transform the {@code optionalField} to a {@code SerializableOptional} when writing the object and after reading
  * such an instance transform it back to an {@code Optional}.
- * <p>
- * <h3>Code Example</h3>
+ * </p>
+ * <h3>Example</h3>
  *
  * <pre>
  * private void writeObject(ObjectOutputStream out) throws IOException {
@@ -40,36 +41,42 @@
  *
  * 	in.defaultReadObject();
  * 	optionalField =
- * 		((SerializableOptional<T>) in.readObject()).toOptional();
+ * 		((SerializableOptional&lt;T&gt;) in.readObject()).toOptional();
  * }
  * </pre>
+ *
+ * <h2>Transform On Replace</h2>
  * <p>
- * <h2>Transform On Replace</h2> If the class is serialized using the Serialization Proxy Pattern (see <i>Effective
- * Java, 2nd Edition</i> by Joshua Bloch, Item 78), the proxy can have an instance of {@link SerializableOptional} to
- * clearly denote the field as being optional.
+ * If the class is serialized using the Serialization Proxy Pattern (see <i>Effective Java, 2nd Edition</i> by Joshua
+ * Bloch, Item 78), the proxy can have an instance of {@link SerializableOptional} to clearly denote the field as being
+ * optional.
  * <p>
  * In this case, the proxy needs to transform the {@code Optional} to {@code SerializableOptional} in its constructor
  * (using {@link SerializableOptional#fromOptional(Optional)}) and the other way in {@code readResolve()} (with
  * {@link SerializableOptional#asOptional()}).
+ * </p>
+ * <h2>Transform On Access</h2>
  * <p>
- * <h2>Transform On Access</h2> The field can be declared as {@code SerializableOptional<T> optionalField}. This will
- * include it in the (de)serialization process so it does not need to be customized.
+ * The field can be declared as {@code SerializableOptional<T> optionalField}. This will include it in the
+ * (de)serialization process so it does not need to be customized.
  * <p>
  * But methods interacting with the field need to get an {@code Optional} instead. This can easily be done by writing
  * the accessor methods such that they transform the field on each access.
  * <p>
  * Note that {@link #asOptional()} simply returns the {@code Optional} which with this instance was created so no
  * constructor needs to be invoked.
+ * </p>
+ * <h3>Example</h3>
  * <p>
- * <h3>Code Example</h3> Note that it is rarely useful to expose an optional field via accessor methods. Hence the
- * following are private and for use inside the class.
+ * Note that it is rarely useful to expose an optional field via accessor methods. Hence the following are private and
+ * for use inside the class.
  *
  * <pre>
- * private Optional<T> getOptionalField() {
+ * private Optional&lt;T&gt; getOptionalField() {
  * 	return optionalField.asOptional();
  * }
  *
- * private void setOptionalField(Optional<T> optionalField) {
+ * private void setOptionalField(Optional&lt;T&gt; optionalField) {
  * 	this.optionalField = SerializableOptional.fromOptional(optionalField);
  * }
  * </pre>