ISSUE #247: Missing JavaDoc for classes

Descriptions of the changes in this PR:

- Addressed the `TODO` comments by adding JavaDoc
- Make sure there is a Github issue for each unaddressed `TODO` comment

Author: Sijie Guo <sijie@apache.org>

Reviewers: Enrico Olivelli <eolivelli@apache.org>

This closes #285 from sijie/issue_247, closes #247

bookkeeper-benchmark/src/main/java/org/apache/bookkeeper/benchmark/BenchBookie.java

@@ -49,7 +49,7 @@
 import io.netty.channel.nio.NioEventLoopGroup;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A utility class used for benchmarking the performance of bookies.
  */
 public class BenchBookie {
     static final Logger LOG = LoggerFactory.getLogger(BenchBookie.class);

bookkeeper-benchmark/src/main/java/org/apache/bookkeeper/benchmark/BenchReadThroughputLatency.java

@@ -48,7 +48,7 @@
 import static com.google.common.base.Charsets.UTF_8;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A benchmark that benchmarks the read throughput and latency.
  */
 public class BenchReadThroughputLatency {
     static final Logger LOG = LoggerFactory.getLogger(BenchReadThroughputLatency.class);

bookkeeper-benchmark/src/main/java/org/apache/bookkeeper/benchmark/BenchThroughputLatency.java

@@ -57,7 +57,7 @@
 import static com.google.common.base.Charsets.UTF_8;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A benchmark that benchmarks write throughput and latency.
  */
 public class BenchThroughputLatency implements AddCallback, Runnable {
     static final Logger LOG = LoggerFactory.getLogger(BenchThroughputLatency.class);

bookkeeper-benchmark/src/main/java/org/apache/bookkeeper/benchmark/MySqlClient.java

@@ -35,7 +35,7 @@
 import org.apache.zookeeper.KeeperException;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A mysql client performing writes and reads that used for benchmark comparison with BookKeeper.
  */
 public class MySqlClient {
     static final Logger LOG = LoggerFactory.getLogger(MySqlClient.class);
@@ -67,8 +67,6 @@ public MySqlClient(String hostport, String user, String pass)
             stmt.execute("create table data(transaction_id bigint PRIMARY KEY AUTO_INCREMENT, content TEXT);");
             LOG.info("Database initialization terminated");
         } catch (SQLException e) {
-
-            // TODO Auto-generated catch block
             e.printStackTrace();
         }
     }

bookkeeper-benchmark/src/main/java/org/apache/bookkeeper/benchmark/package-info.java

@@ -18,6 +18,6 @@
  *
  */
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * Benchmark utils for benchmarking the performance of Apache BookKeeper.
  */
-package org.apache.bookkeeper.benchmark;
+package org.apache.bookkeeper.benchmark;

bookkeeper-server/src/main/java/org/apache/bookkeeper/auth/AuthCallbacks.java

@@ -22,7 +22,7 @@
 public abstract class AuthCallbacks {
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Generic callback used in authentication providers.
      */
     public interface GenericCallback<T> {
 

bookkeeper-server/src/main/java/org/apache/bookkeeper/auth/AuthProviderFactoryFactory.java

@@ -30,7 +30,7 @@
 import org.apache.bookkeeper.bookie.BookieConnectionPeer;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A factory to manage the authentication provider factories.
  */
 public class AuthProviderFactoryFactory {
 

bookkeeper-server/src/main/java/org/apache/bookkeeper/auth/BookieAuthProvider.java

@@ -28,12 +28,13 @@
 
 /**
  * Bookie authentication provider interface.
- * This must be implemented by any party wishing to implement
+ *
+ * <p>This must be implemented by any party wishing to implement
  * an authentication mechanism for bookkeeper connections.
  */
 public interface BookieAuthProvider {
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * A factory to create the bookie authentication provider.
      */
     interface Factory {
         /**

bookkeeper-server/src/main/java/org/apache/bookkeeper/auth/ClientAuthProvider.java

@@ -32,7 +32,7 @@
  */
 public interface ClientAuthProvider {
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * A factory to create the authentication providers for bookkeeper clients.
      */
     interface Factory {
         /**

bookkeeper-server/src/main/java/org/apache/bookkeeper/auth/package-info.java

@@ -15,6 +15,6 @@
  * the License.
  */
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * Classes used to handle authentication in bookies and clients.
  */
-package org.apache.bookkeeper.auth;
+package org.apache.bookkeeper.auth;

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/BookKeeperServerStats.java

@@ -21,7 +21,7 @@
 package org.apache.bookkeeper.bookie;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A utility class used for managing the <i>stats constants</i> used in server side.
  */
 public interface BookKeeperServerStats {
 

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/Bookie.java

@@ -178,7 +178,7 @@ public class Bookie extends BookieCriticalThread {
     private final OpStatsLogger readBytesStats;
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Exception is thrown when no such a ledger is found in this bookie.
      */
     public static class NoLedgerException extends IOException {
         private static final long serialVersionUID = 1L;
@@ -193,7 +193,7 @@ public long getLedgerId() {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Exception is thrown when no such an entry is found in this bookie.
      */
     public static class NoEntryException extends IOException {
         private static final long serialVersionUID = 1L;

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/BookieException.java

@@ -22,7 +22,8 @@
  */
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * Signals that a Bookie exception of some sort has occurred. This class
+ * is the general class of exceptions produced by failed or interrupted bookie operations.
  */
 @SuppressWarnings("serial")
 public abstract class BookieException extends Exception {
@@ -58,7 +59,7 @@ public static BookieException create(int code) {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * An exception code indicates the failure reason.
      */
     public interface Code {
         int OK = 0;
@@ -119,7 +120,7 @@ public String getMessage(int code) {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signals that an unauthorized operation attempts to access the data in a bookie.
      */
     public static class BookieUnauthorizedAccessException extends BookieException {
         public BookieUnauthorizedAccessException() {
@@ -128,7 +129,7 @@ public BookieUnauthorizedAccessException() {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signals that an illegal operation attempts to access the data in a bookie.
      */
     public static class BookieIllegalOpException extends BookieException {
         public BookieIllegalOpException() {
@@ -137,7 +138,7 @@ public BookieIllegalOpException() {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signals that a ledger has been fenced in a bookie. No more entries can be appended to that ledger.
      */
     public static class LedgerFencedException extends BookieException {
         public LedgerFencedException() {
@@ -146,7 +147,9 @@ public LedgerFencedException() {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signal that an invalid cookie is found when starting a bookie.
+     *
+     * <p>This exception is mainly used for detecting if there is any malformed configuration in a bookie.
      */
     public static class InvalidCookieException extends BookieException {
         public InvalidCookieException() {
@@ -163,7 +166,7 @@ public InvalidCookieException(Throwable cause) {
     }
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signals that an exception occurs on upgrading a bookie.
      */
     public static class UpgradeException extends BookieException {
         public UpgradeException() {
@@ -179,6 +182,9 @@ public UpgradeException(String reason) {
         }
     }
 
+    /**
+     * Signals when multiple ledger/journal directories are mounted in same disk partition.
+     */
     public static class DiskPartitionDuplicationException extends BookieException {
         public DiskPartitionDuplicationException() {
             super(Code.DiskPartitionDuplicationException);

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/BufferedChannelBase.java

@@ -21,7 +21,8 @@
 import java.nio.channels.FileChannel;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A {@code BufferedChannelBase} adds functionlity to an existing file channel, the ability
+ * to buffer the input and output data. This class is a base class for wrapping the {@link FileChannel}.
  */
 public abstract class BufferedChannelBase {
     protected final FileChannel fileChannel;

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/CheckpointSourceList.java

@@ -26,7 +26,7 @@
 import com.google.common.collect.Lists;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A {@code CheckpointSourceList} manages a list of {@link CheckpointSource}s.
  */
 public class CheckpointSourceList implements CheckpointSource {
 

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/EntryKey.java

@@ -23,7 +23,9 @@
 import java.util.Comparator;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * An {@code EntryKey} represents an entry in a ledger, identified by {@code ledgerId} and {@code entryId}.
+ *
+ * <p>This class is mainly used in {@code SortedLedgerStorage} for managing and sorting the entries in the memtable.
  */
 public class EntryKey {
     long ledgerId;

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/EntryLocation.java

@@ -22,7 +22,7 @@
 package org.apache.bookkeeper.bookie;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * An {@code EntryLocation} represents the location where an entry is stored.
  */
 public class EntryLocation {
     public final long ledger;
@@ -34,4 +34,4 @@ public EntryLocation(long ledger, long entry, long location) {
         this.entry = entry;
         this.location = location;
     }
-}
+}

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/IndexPersistenceMgr.java

@@ -48,7 +48,7 @@
 import static org.apache.bookkeeper.bookie.BookKeeperServerStats.NUM_OPEN_LEDGERS;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A {@code IndexPersistenceMgr} is responsible for managing the persistence state for the index in a bookie.
  */
 public class IndexPersistenceMgr {
     private static final Logger LOG = LoggerFactory.getLogger(IndexPersistenceMgr.class);

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/InterleavedLedgerStorage.java

@@ -52,8 +52,9 @@
 import static org.apache.bookkeeper.bookie.BookKeeperServerStats.STORAGE_GET_OFFSET;
 
 /**
- * Interleave ledger storage
- * This ledger storage implementation stores all entries in a single
+ * Interleave ledger storage.
+ *
+ * <p>This ledger storage implementation stores all entries in a single
  * file and maintains an index file for each ledger.
  */
 public class InterleavedLedgerStorage implements CompactableLedgerStorage, EntryLogListener {
@@ -463,7 +464,7 @@ public void onRotateEntryLog() {
         // in ledger storage and ready to be synced to disk.
         // TODO: we could consider remove checkpointSource and checkpointSouce#newCheckpoint
         // later if we provide kind of LSN (Log/Journal Squeuence Number)
-        // mechanism when adding entry.
+        // mechanism when adding entry. {@link https://github.com/apache/bookkeeper/issues/279}
         checkpointHolder.setNextCheckpoint(checkpointSource.newCheckpoint());
     }
 }

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/LastAddConfirmedUpdateNotification.java

@@ -21,7 +21,9 @@
 package org.apache.bookkeeper.bookie;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A signal object is used for notifying the observers when the {@code LastAddConfirmed} is advanced.
+ *
+ * <p>The signal object contains the latest {@code LastAddConfirmed} and when the {@code LastAddConfirmed} is advanced.
  */
 public class LastAddConfirmedUpdateNotification {
     public long lastAddConfirmed;

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/LedgerStorage.java

@@ -31,8 +31,7 @@
 import org.apache.bookkeeper.meta.LedgerManager;
 
 /**
- * Interface for storing ledger data
- * on persistant storage.
+ * Interface for storing ledger data on persistent storage.
  */
 public interface LedgerStorage {
 
@@ -148,7 +147,7 @@ void initialize(ServerConfiguration conf, LedgerManager ledgerManager, LedgerDir
     void deleteLedger(long ledgerId) throws IOException;
 
     /**
-     * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+     * Signals that a ledger is deleted by the garbage collection thread.
      */
     interface LedgerDeletionListener {
         void ledgerDeleted(long ledgerId);

bookkeeper-server/src/main/java/org/apache/bookkeeper/bookie/LedgerStorageFactory.java

@@ -25,7 +25,7 @@
 import org.apache.bookkeeper.util.ReflectionUtils;
 
 /**
- * @TODO: Write JavaDoc comment {@link https://github.com/apache/bookkepeer/issues/247}
+ * A factory that creates {@link LedgerStorage} by reflection.
  */
 public class LedgerStorageFactory {
     public static LedgerStorage createLedgerStorage(String name) throws IOException {