Merge pull request iluwatar#716 from baislsl/javadoc-fix

Improve Javadoc

Author: iluwatar

caching/src/main/java/com/iluwatar/caching/App.java

@@ -52,12 +52,12 @@
  * whether the data is coming from the cache or the DB (i.e. separation of concern). The AppManager
  * ({@link AppManager}) handles the transaction of data to-and-from the underlying data store
  * (depending on the preferred caching policy/strategy).
- *
- * <i>App --> AppManager --> CacheStore/LRUCache/CachingPolicy --> DBManager</i>
+ * <p>
+ * <i>{@literal App --> AppManager --> CacheStore/LRUCache/CachingPolicy --> DBManager} </i>
  * </p>
  *
  * @see CacheStore
- * @See LRUCache
+ * @see LruCache
  * @see CachingPolicy
  *
  */

dao/src/main/java/com/iluwatar/dao/InMemoryCustomerDao.java

@@ -31,7 +31,7 @@
 /**
  * An in memory implementation of {@link CustomerDao}, which stores the customers in JVM memory
  * and data is lost when the application exits.
- * <br/>
+ * <br>
  * This implementation is useful as temporary database or for testing.
  */
 public class InMemoryCustomerDao implements CustomerDao {

data-bus/src/main/java/com/iluwatar/databus/App.java

@@ -34,8 +34,7 @@
 /**
  * The Data Bus pattern
  * <p>
- * <p>{@see http://wiki.c2.com/?DataBusPattern}</p>
- * <p>
+ * @see <a href="http://wiki.c2.com/?DataBusPattern">http://wiki.c2.com/?DataBusPattern</a>
  * <p>The Data-Bus pattern provides a method where different parts of an application may
  * pass messages between each other without needing to be aware of the other's existence.</p>
  * <p>Similar to the {@code ObserverPattern}, members register themselves with the {@link DataBus}

event-driven-architecture/src/main/java/com/iluwatar/eda/App.java

@@ -33,7 +33,7 @@
 /**
  * An event-driven architecture (EDA) is a framework that orchestrates behavior around the
  * production, detection and consumption of events as well as the responses they evoke. An event is
- * any identifiable occurrence that has significance for system hardware or software. <p/> The
+ * any identifiable occurrence that has significance for system hardware or software. <p> The
  * example below uses an {@link EventDispatcher} to link/register {@link Event} objects to their
  * respective handlers once an {@link Event} is dispatched, it's respective handler is invoked and
  * the {@link Event} is handled accordingly.

factory-kit/src/main/java/com/iluwatar/factorykit/App.java

@@ -45,7 +45,7 @@ public class App {
   /**
    * Program entry point.
    *
-   * @param args @param args command line args
+   * @param args command line args
    */
   public static void main(String[] args) {
     WeaponFactory factory = WeaponFactory.factory(builder -> {

feature-toggle/src/main/java/com/iluwatar/featuretoggle/App.java

@@ -67,7 +67,7 @@ public class App {
    *  @see UserGroup
    *  @see Service
    *  @see PropertiesFeatureToggleVersion
-   *  @see com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion;
+   *  @see com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion
    */
   public static void main(String[] args) {
 

feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/Service.java

@@ -47,7 +47,7 @@ public interface Service {
   /**
    * Returns if the welcome message to be displayed will be the enhanced version.
    *
-   * @return Boolean {@value true} if enhanced.
+   * @return Boolean {@code true} if enhanced.
    */
   boolean isEnhanced();
 

feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/propertiesversion/PropertiesFeatureToggleVersion.java

@@ -91,7 +91,7 @@ public String getWelcomeMessage(final User user) {
    * see the value of the boolean that was set in the constructor
    * {@link PropertiesFeatureToggleVersion#PropertiesFeatureToggleVersion(Properties)}
    *
-   * @return Boolean value {@value true} if enhanced.
+   * @return Boolean value {@code true} if enhanced.
    */
   @Override
   public boolean isEnhanced() {

feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/tieredversion/TieredFeatureToggleVersion.java

@@ -65,7 +65,7 @@ public String getWelcomeMessage(User user) {
    * is driven by the user group. This method is a little redundant. However can be used to show that there is an
    * enhanced version available.
    *
-   * @return Boolean value {@value true} if enhanced.
+   * @return Boolean value {@code true} if enhanced.
    */
   @Override
   public boolean isEnhanced() {

guarded-suspension/src/main/java/com/iluwatar/guarded/suspension/GuardedQueue.java

@@ -32,7 +32,7 @@
  * Guarded Queue is an implementation for Guarded Suspension Pattern
  * Guarded suspension pattern is used to handle a situation when you want to execute a method
  * on an object which is not in a proper state.
- * @see http://java-design-patterns.com/patterns/guarded-suspension/
+ * @see <a href="http://java-design-patterns.com/patterns/guarded-suspension/">http://java-design-patterns.com/patterns/guarded-suspension/</a>
  */
 public class GuardedQueue {
   private static final Logger LOGGER = LoggerFactory.getLogger(GuardedQueue.class);

half-sync-half-async/src/main/java/com/iluwatar/halfsynchalfasync/App.java

@@ -33,31 +33,31 @@
  * {@link AsyncTask} and {@link AsynchronousService}.
  * 
  * <p>
- * <i>PROBLEM</i> <br/>
+ * <i>PROBLEM</i> <br>
  * A concurrent system have a mixture of short duration, mid duration and long duration tasks. Mid
  * or long duration tasks should be performed asynchronously to meet quality of service
  * requirements.
  * 
  * <p>
- * <i>INTENT</i> <br/>
+ * <i>INTENT</i> <br>
  * The intent of this pattern is to separate the the synchronous and asynchronous processing in the
  * concurrent application by introducing two intercommunicating layers - one for sync and one for
  * async. This simplifies the programming without unduly affecting the performance.
  * 
  * <p>
- * <i>APPLICABILITY</i> <br/>
+ * <i>APPLICABILITY</i> <br>
  * UNIX network subsystems - In operating systems network operations are carried out
- * asynchronously with help of hardware level interrupts.<br/>
+ * asynchronously with help of hardware level interrupts.<br>
  * CORBA - At the asynchronous layer one thread is associated with each socket that is connected
  * to the client. Thread blocks waiting for CORBA requests from the client. On receiving request it
  * is inserted in the queuing layer which is then picked up by synchronous layer which processes the
- * request and sends response back to the client.<br/>
+ * request and sends response back to the client.<br>
  * Android AsyncTask framework - Framework provides a way to execute long running blocking
  * calls, such as downloading a file, in background threads so that the UI thread remains free to
- * respond to user inputs.<br/>
+ * respond to user inputs.<br>
  * 
  * <p>
- * <i>IMPLEMENTATION</i> <br/>
+ * <i>IMPLEMENTATION</i> <br>
  * The main method creates an asynchronous service which does not block the main thread while the
  * task is being performed. The main thread continues its work which is similar to Async Method
  * Invocation pattern. The difference between them is that there is a queuing layer between

hexagonal/src/main/java/com/iluwatar/hexagonal/App.java

@@ -50,13 +50,13 @@
  * from the services it uses.<p>
  * 
  * The primary ports for the application are console interfaces
- * {@link ConsoleAdministration} through which the lottery round is
- * initiated and run and {@link ConsoleLottery} that allows players to
+ * {@link com.iluwatar.hexagonal.administration.ConsoleAdministration} through which the lottery round is
+ * initiated and run and {@link com.iluwatar.hexagonal.service.ConsoleLottery} that allows players to
  * submit lottery tickets for the draw.<p>
  * 
- * The secondary ports that application core uses are {@link WireTransfers}
- * which is a banking service, {@link LotteryEventLog} that delivers
- * eventlog as lottery events occur and {@link LotteryTicketRepository}
+ * The secondary ports that application core uses are {@link com.iluwatar.hexagonal.banking.WireTransfers}
+ * which is a banking service, {@link com.iluwatar.hexagonal.eventlog.LotteryEventLog} that delivers
+ * eventlog as lottery events occur and {@link com.iluwatar.hexagonal.database.LotteryTicketRepository}
  * that is the storage for the lottery tickets.
  *
  */

mediator/src/test/java/com/iluwatar/mediator/PartyMemberTest.java

@@ -110,7 +110,7 @@ public void testAct(Supplier<PartyMember> memberSupplier) {
   }
 
   /**
-   * Verify if {@link PartyMember#toString()} generate the expected output
+   * Verify if {@link PartyMemberBase#toString()} generate the expected output
    */
   @ParameterizedTest
   @MethodSource("dataProvider")

naked-objects/webapp/src/main/java/domainapp/webapp/SimpleApplication.java

@@ -51,14 +51,14 @@
  * See:
  * 
  * <pre>
- * &lt;filter>
- *   &lt;filter-name>wicket&lt;/filter-name>
- *    &lt;filter-class>org.apache.wicket.protocol.http.WicketFilter&lt;/filter-class>
- *    &lt;init-param>
- *      &lt;param-name>applicationClassName&lt;/param-name>
- *      &lt;param-value>webapp.SimpleApplication&lt;/param-value>
- *    &lt;/init-param>
- * &lt;/filter>
+ * &lt;filter&gt;
+ *   &lt;filter-name&gt;wicket&lt;/filter-name&gt;
+ *    &lt;filter-class&gt;org.apache.wicket.protocol.http.WicketFilter&lt;/filter-class&gt;
+ *    &lt;init-param&gt;
+ *      &lt;param-name&gt;applicationClassName&lt;/param-name&gt;
+ *      &lt;param-value&gt;webapp.SimpleApplication&lt;/param-value&gt;
+ *    &lt;/init-param&gt;
+ * &lt;/filter&gt;
  * </pre>
  * 
  */
@@ -69,7 +69,7 @@ public class SimpleApplication extends IsisWicketApplication {
   /**
    * uncomment for a (slightly hacky) way of allowing logins using query args, eg:
    * 
-   * <tt>?user=sven&pass=pass</tt>
+   * <tt>{@code ?user=sven&pass=pass}</tt>
    * 
    * <p>
    * for demos only, obvious.

observer/src/main/java/com/iluwatar/observer/generic/Observable.java

@@ -26,7 +26,7 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
- * Generic observer inspired by Java Generics and Collection by Naftalin & Wadler
+ * Generic observer inspired by Java Generics and Collection by {@literal Naftalin & Wadler}
  *
  * @param <S> Subject
  * @param <O> Observer

reactor/src/main/java/com/iluwatar/reactor/app/App.java

@@ -39,13 +39,13 @@
  * Service where it listens on multiple TCP or UDP sockets for incoming log requests.
  * 
  * <p>
- * <i>INTENT</i> <br/>
+ * <i>INTENT</i> <br>
  * The Reactor design pattern handles service requests that are delivered concurrently to an
  * application by one or more clients. The application can register specific handlers for processing
  * which are called by reactor on specific events.
  * 
  * <p>
- * <i>PROBLEM</i> <br/>
+ * <i>PROBLEM</i> <br>
  * Server applications in a distributed system must handle multiple clients that send them service
  * requests. Following forces need to be resolved:
  * <ul>
@@ -56,31 +56,37 @@
  * </ul>
  * 
  * <p>
- * <i>PARTICIPANTS</i> <br/>
+ * <i>PARTICIPANTS</i> <br>
  * <ul>
- * <li>Synchronous Event De-multiplexer</li> {@link NioReactor} plays the role of synchronous event
- * de-multiplexer. It waits for events on multiple channels registered to it in an event loop.
- * 
+ * <li>Synchronous Event De-multiplexer
  * <p>
- * <li>Initiation Dispatcher</li> {@link NioReactor} plays this role as the application specific
- * {@link ChannelHandler}s are registered to the reactor.
- * 
+ *     {@link NioReactor} plays the role of synchronous event de-multiplexer.
+ * It waits for events on multiple channels registered to it in an event loop.
+ * </p>
+ * </li>
+ * <li>Initiation Dispatcher
  * <p>
- * <li>Handle</li> {@link AbstractNioChannel} acts as a handle that is registered to the reactor.
+ *     {@link NioReactor} plays this role as the application specific {@link ChannelHandler}s
+ * are registered to the reactor.
+ * </p>
+ * </li>
+ * <li>Handle
+ * <p>
+ *     {@link AbstractNioChannel} acts as a handle that is registered to the reactor.
  * When any events occur on a handle, reactor calls the appropriate handler.
- * 
+ * </p>
+ * </li>
+ * <li>Event Handler
  * <p>
- * <li>Event Handler</li> {@link ChannelHandler} acts as an event handler, which is bound to a
+ *      {@link ChannelHandler} acts as an event handler, which is bound to a
  * channel and is called back when any event occurs on any of its associated handles. Application
  * logic resides in event handlers.
+ * </p>
+ * </li>
  * </ul>
- * 
- * <p>
  * The application utilizes single thread to listen for requests on all ports. It does not create a
  * separate thread for each client, which provides better scalability under load (number of clients
  * increase).
- * 
- * <p>
  * The example uses Java NIO framework to implement the Reactor.
  * 
  */

reactor/src/main/java/com/iluwatar/reactor/app/AppClient.java

@@ -108,7 +108,7 @@ static class TcpLoggingClient implements Runnable {
      * Creates a new TCP logging client.
      * 
      * @param clientName the name of the client to be sent in logging requests.
-     * @param port the port on which client will send logging requests.
+     * @param serverPort the port on which client will send logging requests.
      */
     public TcpLoggingClient(String clientName, int serverPort) {
       this.clientName = clientName;

reactor/src/main/java/com/iluwatar/reactor/framework/AbstractNioChannel.java

@@ -141,7 +141,7 @@ void flush(SelectionKey key) throws IOException {
    * when this method returns. It will be written when the channel is flushed.
    * 
    * <p>
-   * This method is used by the {@link ChannelHandler} to send reply back to the client. <br/>
+   * This method is used by the {@link ChannelHandler} to send reply back to the client. <br>
    * Example:
    * 
    * <pre>

reactor/src/main/java/com/iluwatar/reactor/framework/Dispatcher.java

@@ -28,7 +28,7 @@
  * Represents the event dispatching strategy. When {@link NioReactor} senses any event on the
  * registered {@link AbstractNioChannel}s then it de-multiplexes the event type, read or write or
  * connect, and then calls the {@link Dispatcher} to dispatch the read events. This decouples the
- * I/O processing from application specific processing. <br/>
+ * I/O processing from application specific processing. <br>
  * Dispatcher should call the {@link ChannelHandler} associated with the channel on which event
  * occurred.
  * 

reactor/src/main/java/com/iluwatar/reactor/framework/SameThreadDispatcher.java

@@ -37,7 +37,7 @@
 public class SameThreadDispatcher implements Dispatcher {
 
   /**
-   * Dispatches the read event in the context of caller thread. <br/>
+   * Dispatches the read event in the context of caller thread. <br>
    * Note this is a blocking call. It returns only after the associated handler has handled the read
    * event.
    */

reactor/src/main/java/com/iluwatar/reactor/framework/ThreadPoolDispatcher.java

@@ -47,7 +47,7 @@ public ThreadPoolDispatcher(int poolSize) {
 
   /**
    * Submits the work of dispatching the read event to worker pool, where it gets picked up by
-   * worker threads. <br/>
+   * worker threads. <br>
    * Note that this is a non-blocking call and returns immediately. It is not guaranteed that the
    * event has been handled by associated handler.
    */

reader-writer-lock/src/main/java/com/iluwatar/reader/writer/lock/ReaderWriterLock.java

@@ -50,9 +50,9 @@ public class ReaderWriterLock implements ReadWriteLock {
   /**
    * Global mutex is used to indicate that whether reader or writer gets the lock in the moment.
    * <p>
-   * 1. When it contains the reference of {@link readerLock}, it means that the lock is acquired by the reader, another
+   * 1. When it contains the reference of {@link #readerLock}, it means that the lock is acquired by the reader, another
    * reader can also do the read operation concurrently. <br>
-   * 2. When it contains the reference of reference of {@link writerLock}, it means that the lock is acquired by the
+   * 2. When it contains the reference of reference of {@link #writerLock}, it means that the lock is acquired by the
    * writer exclusively, no more reader or writer can get the lock.
    * <p>
    * This is the most important field in this class to control the access for reader/writer.

resource-acquisition-is-initialization/src/main/java/com/iluwatar/resource/acquisition/is/initialization/App.java

@@ -33,13 +33,13 @@
  * In RAII resource is tied to object lifetime: resource allocation is done during object creation
  * while resource deallocation is done during object destruction.
  * <p>
- * In Java RAII is achieved with try-with-resources statement and interfaces {@link Closeable} and
+ * In Java RAII is achieved with try-with-resources statement and interfaces {@link java.io.Closeable} and
  * {@link AutoCloseable}. The try-with-resources statement ensures that each resource is closed at
  * the end of the statement. Any object that implements {@link java.lang.AutoCloseable}, which
  * includes all objects which implement {@link java.io.Closeable}, can be used as a resource.
  *
  * In this example, {@link SlidingDoor} implements {@link AutoCloseable} and {@link TreasureChest}
- * implements {@link Closeable}. Running the example, we can observe that both resources are
+ * implements {@link java.io.Closeable}. Running the example, we can observe that both resources are
  * automatically closed.
  * <p>
  * http://docs.oracle.com/javase/7/docs/technotes/guides/language/try-with-resources.html

service-locator/src/main/java/com/iluwatar/servicelocator/Service.java

@@ -24,7 +24,7 @@
 
 /**
  * This is going to be the parent service interface which we will use to create our services. All
- * services will have a <li>service name</li> <li>unique id</li> <li>execution work flow</li>
+ * services will have a <ul><li>service name</li> <li>unique id</li> <li>execution work flow</li></ul>
  * 
  * @author saifasif
  *

singleton/src/main/java/com/iluwatar/singleton/App.java

@@ -28,35 +28,35 @@
 /**
  * Singleton pattern ensures that the class can have only one existing instance per Java classloader
  * instance and provides global access to it.
- * <p/>
+ * <p>
  * One of the risks of this pattern is that bugs resulting from setting a singleton up in a
  * distributed environment can be tricky to debug, since it will work fine if you debug with a
  * single classloader. Additionally, these problems can crop up a while after the implementation of
  * a singleton, since they may start out synchronous and only become async with time, so you it may
  * not be clear why you are seeing certain changes in behaviour.
- * <p/>
+ * <p>
  * There are many ways to implement the Singleton. The first one is the eagerly initialized instance
  * in {@link IvoryTower}. Eager initialization implies that the implementation is thread safe. If
  * you can afford giving up control of the instantiation moment, then this implementation will suit
  * you fine.
- * <p/>
+ * <p>
  * The other option to implement eagerly initialized Singleton is enum based Singleton. The example
  * is found in {@link EnumIvoryTower}. At first glance the code looks short and simple. However, you
  * should be aware of the downsides including committing to implementation strategy, extending the
  * enum class, serializability and restrictions to coding. These are extensively discussed in Stack
  * Overflow:
  * http://programmers.stackexchange.com/questions/179386/what-are-the-downsides-of-implementing
  * -a-singleton-with-javas-enum
- * <p/>
+ * <p>
  * {@link ThreadSafeLazyLoadedIvoryTower} is a Singleton implementation that is initialized on
  * demand. The downside is that it is very slow to access since the whole access method is
  * synchronized.
- * <p/>
+ * <p>
  * Another Singleton implementation that is initialized on demand is found in
  * {@link ThreadSafeDoubleCheckLocking}. It is somewhat faster than
  * {@link ThreadSafeLazyLoadedIvoryTower} since it doesn't synchronize the whole access method but
  * only the method internals on specific conditions.
- * <p/>
+ * <p>
  * Yet another way to implement thread safe lazily initialized Singleton can be found in
  * {@link InitializingOnDemandHolderIdiom}. However, this implementation requires at least Java 8
  * API level to work.