DRILL-6389: Fixed building javadocs

 - Added documentation about how to build javadocs
 - Fixed some of the javadoc warnings

closes #1276

11 files changed, 36 insertions, 46 deletions

diff --git a/drill-yarn/pom.xml b/drill-yarn/pom.xml
index 7cb2a9346..6bad97a3d 100644
--- a/drill-yarn/pom.xml
+++ b/drill-yarn/pom.xml
@@ -43,7 +43,7 @@
          </configuration>
       </plugin>
         <!-- See http://stackoverflow.com/questions/31173467/maven-cannot-find-git-dotgitdirectory -->
-  <!-- 
+  <!--
       <plugin>
         <groupId>pl.project13.maven</groupId>
         <artifactId>git-commit-id-plugin</artifactId>
@@ -65,7 +65,7 @@
      -->
     </plugins>
   </build>
-  
+
   <dependencies>
 
     <!-- For YARN client. -->
@@ -75,7 +75,7 @@
       <artifactId>hadoop-yarn-api</artifactId>
       <scope>compile</scope>
     </dependency>
-    
+
     <!--  Included as a reference because this seems to be the only
           way to pick up profile-specific jars. -->
 
@@ -116,7 +116,7 @@
       <version>1.0.13</version>
       <scope>test</scope>
     </dependency>
-    
+
     <!--  Testing -->
     <dependency>
       <groupId>org.apache.drill</groupId>
@@ -132,7 +132,7 @@
 	   <dependency>
 	      <groupId>org.apache.curator</groupId>
 	      <artifactId>curator-test</artifactId>
-	      <version>2.7.1</version>
+	      <version>${curator.test.version}</version>
 	      <scope>test</scope>
 	      <exclusions>
           <exclusion>
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterController.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterController.java
index 6aaa18b11..3fcc35f55 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterController.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterController.java
@@ -62,7 +62,6 @@ public interface ClusterController extends RegistryHandler {
    *
    * @param containers
    *          the set of containers provided by YARN
-   * @return the set of tasks to launch
    */
 
   void containersAllocated(List<Container> containers);
@@ -146,8 +145,6 @@ public interface ClusterController extends RegistryHandler {
    * Called by the main thread to wait for the normal shutdown of the
    * controller. Such shutdown occurs when the admin sends a sutdown
    * command from the UI or REST API.
-   *
-   * @return
    */
 
   boolean waitForCompletion();
@@ -176,8 +173,6 @@ public interface ClusterController extends RegistryHandler {
   /**
    * Return the target number of tasks that the controller seeks to maintain.
    * This is the sum across all pools.
-   *
-   * @return
    */
 
   int getTargetCount();
@@ -190,17 +185,16 @@ public interface ClusterController extends RegistryHandler {
    * when reducing cluster size.
    *
    * @param id
-   * @return
    */
 
   boolean cancelTask(int id);
 
   /**
    * Whether this distribution of YARN supports disk resources.
-   * @return
+   * @return True if this distribution of YARN supports disk resources. False otherwise.
    */
 
   boolean supportsDiskResource();
 
   int getFreeNodeCount();
-}
\ No newline at end of file
+}
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterControllerImpl.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterControllerImpl.java
index 3c011ec54..e611b6f02 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterControllerImpl.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/ClusterControllerImpl.java
@@ -311,7 +311,7 @@ public class ClusterControllerImpl implements ClusterController {
    * This approximation <b>does not</b> consider whether the node
    * has sufficient resources to run a task; only whether the node
    * itself exists.
-   * @return
+   * @return The approximate number of free YARN nodes.
    */
 
   @Override
@@ -782,4 +782,4 @@ public class ClusterControllerImpl implements ClusterController {
 
   @Override
   public void registryDown() { shutDown( ); }
-}
\ No newline at end of file
+}
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/PersistentTaskScheduler.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/PersistentTaskScheduler.java
index 73a045fa6..bfa636d49 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/PersistentTaskScheduler.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/PersistentTaskScheduler.java
@@ -79,7 +79,7 @@ public abstract class PersistentTaskScheduler extends AbstractScheduler {
    * running tasks to target level. Thus, a persistent cluster
    * will normally report 100% progress.
    *
-   * @return
+   * @return The progress of persistent tasks.
    */
 
   @Override
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/Scheduler.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/Scheduler.java
index 7f8be0c9b..bb1ce9dfd 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/Scheduler.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/Scheduler.java
@@ -72,8 +72,6 @@ public interface Scheduler {
   /**
    * Whether tasks from this scheduler should incorporate app startup/shutdown
    * acknowledgements (acks) into the task lifecycle.
-   *
-   * @return
    */
 
   boolean isTracked();
@@ -83,7 +81,7 @@ public interface Scheduler {
   /**
    * Get the desired number of running tasks.
    *
-   * @return
+   * @return The desired number of running tasks
    */
   int getTarget();
 
@@ -119,7 +117,7 @@ public interface Scheduler {
    * Return an estimate of progress given as a ratio of (work completed, total
    * work).
    *
-   * @return
+   * @return Estimate of progress.
    */
   int[] getProgress();
 
@@ -135,7 +133,7 @@ public interface Scheduler {
   /**
    * For reporting, get the YARN resources requested by processes in
    * this pool.
-   * @return
+   * @return The request spec.
    */
 
   ContainerRequestSpec getResource( );
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerState.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerState.java
index 7a1f8bd02..39e81ce65 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerState.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerState.java
@@ -29,7 +29,7 @@ public interface SchedulerState {
   /**
    * The number of tasks in any active (non-ended) lifecycle state.
    *
-   * @return
+   * @return The number of tasks in any active (non-ended) lifecycle state.
    */
 
   int getTaskCount();
@@ -38,7 +38,8 @@ public interface SchedulerState {
    * The number of active tasks that have been cancelled, but have not yet
    * ended.
    *
-   * @return
+   * @returnThe number of active tasks that have been cancelled, but have not yet
+   * ended.
    */
 
   int getCancelledTaskCount();
@@ -50,7 +51,9 @@ public interface SchedulerState {
    * does not contain any tasks in this state which have previously been
    * cancelled.
    *
-   * @return
+   * @return The list of tasks awaiting a container request to be sent to YARN
+   * or for which a container request has been sent to YARN, but no container
+   * allocation has yet been received.
    */
 
   List<Task> getStartingTasks();
@@ -60,7 +63,7 @@ public interface SchedulerState {
    * tasks are any task for which a container has been assigned, but has not yet
    * received a RM container completion event.
    *
-   * @return
+   * @return The list of active tasks that have not yet been cancelled.
    */
 
   List<Task> getActiveTasks();
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerStateActions.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerStateActions.java
index 65e8f2adc..51884f734 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerStateActions.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/SchedulerStateActions.java
@@ -29,7 +29,7 @@ public interface SchedulerStateActions {
   /**
    * Returns the name of the scheduler associated with this task action group.
    *
-   * @return
+   * @return The name of the scheduler associated with this task action group.
    */
 
   String getName();
@@ -37,7 +37,7 @@ public interface SchedulerStateActions {
   /**
    * Returns the scheduler associated with this task group.
    *
-   * @return
+   * @return The scheduler associated with this task group.
    */
 
   Scheduler getScheduler();
@@ -80,7 +80,7 @@ public interface SchedulerStateActions {
    * differentiates the start state (when no tasks are active) from the end
    * state. The AM will not shut down until all task groups are done.
    *
-   * @return
+   * @return True if this task group is done. False otherwise.
    */
 
   boolean isDone();
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AmRestApi.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AmRestApi.java
index 21ddc4b03..0e6b405c2 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AmRestApi.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AmRestApi.java
@@ -134,9 +134,6 @@ public class AmRestApi extends PageTree
    * set in the Drill-on-YARN configuration file. The purpose is simply to prevent
    * accidental cluster shutdown when experimenting with the REST API; this is
    * not meant to be a security mechanism.
-   *
-   * @param key
-   * @return
    */
 
   @Path("/stop")
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AuthDynamicFeature.java b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AuthDynamicFeature.java
index 12ee267be..c882fe027 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AuthDynamicFeature.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/appMaster/http/AuthDynamicFeature.java
@@ -44,7 +44,7 @@ import java.net.URLEncoder;
  * login page.
  * <p>
  * Shameless copy of
- * {@link org.apache.drill.exec.server.rest.auth.DynamicFeature}; the two
+ * {@link org.apache.drill.exec.server.rest.auth.AuthDynamicFeature}; the two
  * implementations should be merged at some point. The difference is only the
  * log in/log out constant references.
  */
@@ -111,4 +111,4 @@ public class AuthDynamicFeature implements DynamicFeature {
   public static boolean isUserLoggedIn(final SecurityContext sc) {
     return sc != null && sc.getUserPrincipal() != null;
   }
-}
\ No newline at end of file
+}
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKClusterCoordinatorDriver.java b/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKClusterCoordinatorDriver.java
index 3f83ff2bc..171c4b0da 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKClusterCoordinatorDriver.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKClusterCoordinatorDriver.java
@@ -99,7 +99,7 @@ public class ZKClusterCoordinatorDriver implements AMRegistrar {
    * Specify connect string in the form: host:/zkRoot/clusterId
    *
    * @param connect
-   * @return
+   * @return This {@link ZKClusterCoordinatorDriver}.
    * @throws ZKConfigException
    */
   public ZKClusterCoordinatorDriver setConnect(String connect)
@@ -161,7 +161,7 @@ public class ZKClusterCoordinatorDriver implements AMRegistrar {
    * Builds and starts the ZooKeeper cluster coordinator, translating any errors
    * that occur. After this call, the listener will start receiving messages.
    *
-   * @return
+   * @return This {@link ZKClusterCoordinatorDriver}.
    * @throws ZKRuntimeException
    *           if ZK startup fails
    */
@@ -201,7 +201,8 @@ public class ZKClusterCoordinatorDriver implements AMRegistrar {
    * Returns the set of Drillbits registered at the time of the {@link #build()}
    * call. Should be empty for a cluster managed by YARN.
    *
-   * @return
+   * @return The set of Drillbits registered at the time of the {@link #build()}
+   * call.
    */
 
   public List<DrillbitEndpoint> getInitialEndpoints() {
@@ -213,7 +214,7 @@ public class ZKClusterCoordinatorDriver implements AMRegistrar {
    * advertise the HTTP port, so it does not appear in the generated string.
    *
    * @param bit
-   * @return
+   * @return A string representation of a Drillbit.
    */
 
   public static String asString(DrillbitEndpoint bit) {
@@ -266,7 +267,7 @@ public class ZKClusterCoordinatorDriver implements AMRegistrar {
    * notification, and we received the disconnect notification log enough ago
    * that we assume that a timeout has occurred.
    *
-   * @return
+   * @return True if we think zookeeper has failed. False otherwise.
    */
 
   public boolean hasFailed() {
diff --git a/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKRegistry.java b/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKRegistry.java
index 04265787c..d05c5628b 100644
--- a/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKRegistry.java
+++ b/drill-yarn/src/main/java/org/apache/drill/yarn/zk/ZKRegistry.java
@@ -23,6 +23,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+import com.google.common.annotations.VisibleForTesting;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.apache.drill.exec.proto.CoordinationProtos.DrillbitEndpoint;
@@ -134,7 +135,7 @@ public class ZKRegistry
     /**
      * ZK tracking state.
      *
-     * @see {@link State}
+     * See {@link org.apache.drill.yarn.zk.ZKRegistry.DrillbitTracker.State}
      */
 
     protected State state;
@@ -168,8 +169,6 @@ public class ZKRegistry
      * that the task has come online. Tell the task to update its state to
      * record that the task is, in fact, registered in ZK. This indicates a
      * normal, healthy task.
-     *
-     * @param tracker
      */
 
     private void becomeRegistered() {
@@ -178,8 +177,6 @@ public class ZKRegistry
 
     /**
      * Mark that a YARN-managed Drillbit has dropped out of ZK.
-     *
-     * @param registryHandler
      */
 
     public void becomeUnregistered() {
@@ -492,7 +489,7 @@ public class ZKRegistry
    * cases where tasks hang in this state. This is a potential work-around.
    *
    * @param task
-   * @return
+   * @return True if the given task is regestered. False otherwise.
    */
 
   public synchronized boolean isRegistered(Task task) {
@@ -573,9 +570,9 @@ public class ZKRegistry
    * Get the current registry for testing. Why for testing? Because this is
    * unsynchronized. In production code, the map may change out from under you.
    *
-   * @return
+   * @return The current registry.
    */
-
+  @VisibleForTesting
   protected Map<String, DrillbitTracker> getRegistryForTesting() {
     return registry;
   }