helix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From zzh...@apache.org
Subject [2/2] git commit: HELIX-207: Add javadocs to classes and public methods in the top-level package, rb=13548
Date Wed, 14 Aug 2013 20:46:47 GMT
HELIX-207: Add javadocs to classes and public methods in the top-level package, rb=13548


Project: http://git-wip-us.apache.org/repos/asf/incubator-helix/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-helix/commit/f38b3da2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-helix/tree/f38b3da2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-helix/diff/f38b3da2

Branch: refs/heads/master
Commit: f38b3da2988cc00fba95037185a52c3756b507f1
Parents: 9861070
Author: zzhang <zzhang5@uci.edu>
Authored: Wed Aug 14 13:46:37 2013 -0700
Committer: zzhang <zzhang5@uci.edu>
Committed: Wed Aug 14 13:46:37 2013 -0700

----------------------------------------------------------------------
 .../java/org/apache/helix/AccessOption.java     |   6 +-
 .../java/org/apache/helix/BaseDataAccessor.java | 104 +++----
 .../apache/helix/ClusterMessagingService.java   |  48 ++-
 .../java/org/apache/helix/ConfigAccessor.java   |  61 ++--
 .../apache/helix/ControllerChangeListener.java  |   5 +-
 .../main/java/org/apache/helix/Criteria.java    |  73 ++++-
 .../helix/CurrentStateChangeListener.java       |  10 +-
 .../java/org/apache/helix/ExternalCommand.java  |  60 ++--
 .../helix/ExternalViewChangeListener.java       |   8 +-
 .../main/java/org/apache/helix/GroupCommit.java |  15 +-
 .../apache/helix/HealthStateChangeListener.java |  11 +-
 .../main/java/org/apache/helix/HelixAdmin.java  |  51 ++--
 .../java/org/apache/helix/HelixConstants.java   |   3 +
 .../org/apache/helix/HelixDataAccessor.java     |  10 +-
 .../java/org/apache/helix/HelixException.java   |   6 +-
 .../java/org/apache/helix/HelixManager.java     |  38 ++-
 .../org/apache/helix/HelixManagerFactory.java   |  10 +-
 .../apache/helix/HelixManagerProperties.java    |  21 +-
 .../java/org/apache/helix/HelixProperty.java    |  66 ++++-
 .../java/org/apache/helix/HelixTimerTask.java   |   9 +-
 .../apache/helix/IdealStateChangeListener.java  |   4 +-
 .../helix/InstanceConfigChangeListener.java     |   3 +
 .../helix/LiveInstanceChangeListener.java       |   4 +-
 .../apache/helix/LiveInstanceInfoProvider.java  |   5 +-
 .../java/org/apache/helix/MessageListener.java  |   4 +-
 .../org/apache/helix/NotificationContext.java   |  64 +++-
 .../org/apache/helix/PreConnectCallback.java    |   3 +
 .../main/java/org/apache/helix/PropertyKey.java | 290 ++++++++++++++++++-
 .../org/apache/helix/PropertyPathConfig.java    |  17 +-
 .../java/org/apache/helix/PropertyType.java     |  54 ++++
 .../helix/ScopedConfigChangeListener.java       |   3 +
 .../main/java/org/apache/helix/ZNRecord.java    | 195 +++++++++++++
 .../org/apache/helix/ZNRecordAssembler.java     |   8 +
 .../org/apache/helix/ZNRecordBucketizer.java    |  14 +-
 .../java/org/apache/helix/ZNRecordDelta.java    |  38 ++-
 .../java/org/apache/helix/ZNRecordUpdater.java  |   7 +
 36 files changed, 1123 insertions(+), 205 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/AccessOption.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/AccessOption.java b/helix-core/src/main/java/org/apache/helix/AccessOption.java
index eb86fee..8bb5506 100644
--- a/helix-core/src/main/java/org/apache/helix/AccessOption.java
+++ b/helix-core/src/main/java/org/apache/helix/AccessOption.java
@@ -32,7 +32,7 @@ public class AccessOption
   /**
    * Helper method to get zookeeper create mode from options
    * 
-   * @param options
+   * @param options bitmask representing mode; least significant set flag is selected
    * @return zookeeper create mode
    */
   public static CreateMode getMode(int options)
@@ -60,8 +60,8 @@ public class AccessOption
   /**
    * Helper method to get is-throw-exception-on-node-not-exist from options
    * 
-   * @param options
-   * @return
+   * @param options bitmask containing Zookeeper mode options
+   * @return true if in is-throw-exception-on-node-not-exist, false otherwise
    */
   public static boolean isThrowExceptionIfNotExist(int options)
   {

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java b/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
index fcbad00..7c65460 100644
--- a/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
@@ -24,9 +24,13 @@ import java.util.List;
 import org.I0Itec.zkclient.DataUpdater;
 import org.I0Itec.zkclient.IZkChildListener;
 import org.I0Itec.zkclient.IZkDataListener;
-import org.apache.zookeeper.CreateMode;
 import org.apache.zookeeper.data.Stat;
 
+/**
+ * Generic interface for accessing and manipulating data on a backing store like Zookeeper.
+ *
+ * @param <T> The type of record to use
+ */
 public interface BaseDataAccessor<T>
 {
   /**
@@ -34,9 +38,9 @@ public interface BaseDataAccessor<T>
    * create parents if they do not exist. For performance reasons, it may try to create
    * child first and only if it fails it will try to create parent
    * 
-   * @param path
-   * @param record
-   * @return
+   * @param path path to the ZNode to create
+   * @param record the data to write to the ZNode
+   * @return true if creation succeeded, false otherwise (e.g. if the ZNode exists)
    */
   boolean create(String path, T record, int options);
 
@@ -44,10 +48,10 @@ public interface BaseDataAccessor<T>
    * This will always attempt to set the data on existing node. If the znode does not
    * exist it will create it.
    * 
-   * @param path
-   * @param record
+   * @param path path to the ZNode to set
+   * @param record the data to write to the ZNode
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return true if data was successfully set, false otherwise
    */
   boolean set(String path, T record, int options);
 
@@ -55,19 +59,19 @@ public interface BaseDataAccessor<T>
    * This will attempt to merge with existing data by calling znrecord.merge and if it
    * does not exist it will create it znode
    * 
-   * @param path
-   * @param record
+   * @param path path to the ZNode to update
+   * @param updater an update routine for the data to merge in
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return true if data merge succeeded, false otherwise
    */
   boolean update(String path, DataUpdater<T> updater, int options);
 
   /**
-   * This will remove znode and all it's child nodes if any
+   * This will remove znode and all its child nodes if any
    * 
-   * @param path
+   * @param path path to the root ZNode to remove
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return true if the removal succeeded, false otherwise
    */
   boolean remove(String path, int options);
 
@@ -75,10 +79,10 @@ public interface BaseDataAccessor<T>
    * Use it when creating children under a parent node. This will use async api for better
    * performance. If the child already exists it will return false.
    * 
-   * @param parentPath
-   * @param record
+   * @param parentPath paths to the immediate parent ZNodes
+   * @param record List of data to write to each of the children
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return For each child: true if creation succeeded, false otherwise (e.g. if the child exists)
    */
   boolean[] createChildren(List<String> paths, List<T> records, int options);
 
@@ -86,9 +90,10 @@ public interface BaseDataAccessor<T>
    * can set multiple children under a parent node. This will use async api for better
    * performance. If this child does not exist it will create it.
    * 
-   * @param parentPath
-   * @param record
+   * @param parentPath paths to the immediate parent ZNodes
+   * @param record List of data with which to overwrite the corresponding ZNodes
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
+   * @return For each child: true if the data was set, false otherwise
    */
   boolean[] setChildren(List<String> paths, List<T> records, int options);
 
@@ -96,117 +101,116 @@ public interface BaseDataAccessor<T>
    * Can update multiple nodes using async api for better performance. If a child does not
    * exist it will create it.
    * 
-   * @param parentPath
-   * @param record
+   * @param parentPath paths to the immediate parent ZNodes
+   * @param updaters List of update routines for records to merge in
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return For each child, true if the data was merged in, false otherwise
    */
   boolean[] updateChildren(List<String> paths, List<DataUpdater<T>> updaters, int options);
 
   /**
    * remove multiple paths using async api. will remove any child nodes if any
    * 
-   * @param paths
+   * @param paths paths to the ZNodes to remove
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return For each ZNode, true if successfully removed, false otherwise
    */
   boolean[] remove(List<String> paths, int options);
 
   /**
    * Get the {@link T} corresponding to the path
    * 
-   * @param path
+   * @param path path to the ZNode
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return the record data stored at the ZNode
    */
   T get(String path, Stat stat, int options);
 
   /**
    * Get List of {@link T} corresponding to the paths using async api
    * 
-   * @param paths
+   * @param paths paths to the ZNodes
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return List of record data stored at each ZNode
    */
   List<T> get(List<String> paths, List<Stat> stats, int options);
 
   /**
    * Get the children under a parent path using async api
    * 
-   * @param path
+   * @param path path to the immediate parent ZNode
+   * @param stats Zookeeper Stat objects corresponding to each child
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return A list of children of the parent ZNode
    */
   List<T> getChildren(String parentPath, List<Stat> stats, int options);
 
   /**
    * Returns the child names given a parent path
    * 
-   * @param type
-   * @param keys
+   * @param parentPath path to the immediate parent ZNode
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return a list of the names of all of the parent ZNode's children
    */
   List<String> getChildNames(String parentPath, int options);
 
   /**
    * checks if the path exists in zk
    * 
-   * @param path
+   * @param path path to the ZNode to test
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return true if the ZNode exists, false otherwise
    */
   boolean exists(String path, int options);
 
   /**
    * checks if the all the paths exists
    * 
-   * @param paths
+   * @param paths paths to the ZNodes to test
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return for each path, true if a valid ZNode exists, false otherwise
    */
   boolean[] exists(List<String> paths, int options);
 
   /**
    * Get the stats of all the paths
    * 
-   * @param paths
+   * @param paths paths of the ZNodes to query
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return Zookeeper Stat object for each path
    */
   Stat[] getStats(List<String> paths, int options);
 
   /**
-   * Get the stats of all the paths
+   * Get the stats of a single path
    * 
-   * @param paths
+   * @param path path of the ZNode to query
    * @param options Set the type of ZNode see the valid values in {@link AccessOption}
-   * @return
+   * @return Zookeeper Stat object corresponding to the ZNode
    */
   Stat getStat(String path, int options);
 
   /**
    * Subscribe data listener to path
    * 
-   * @param path
-   * @param listener
-   * @return
+   * @param path path to the ZNode to listen to
+   * @param listener the listener to register for changes
    */
   void subscribeDataChanges(String path, IZkDataListener listener);
 
   /**
    * Unsubscribe data listener to path
    * 
-   * @param path
-   * @param listener
+   * @param path path to the ZNode to stop listening to
+   * @param listener the listener currently subscribed to the ZNode
    */
   void unsubscribeDataChanges(String path, IZkDataListener listener);
 
   /**
    * Subscribe child listener to path
    * 
-   * @param path
-   * @param listener
+   * @param path path to the immediate parent ZNode
+   * @param listener the listener to register for changes
    * @return
    */
   List<String> subscribeChildChanges(String path, IZkChildListener listener);
@@ -214,8 +218,8 @@ public interface BaseDataAccessor<T>
   /**
    * Unsubscribe child listener to path
    * 
-   * @param path
-   * @param listener
+   * @param path path to the immediate parent ZNode
+   * @param listener the listener currently subscribed to the children
    */
   void unsubscribeChildChanges(String path, IZkChildListener listener);
 

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java b/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
index dc4a0ad..6bab243 100644
--- a/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
+++ b/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
@@ -40,34 +40,43 @@ public interface ClusterMessagingService
   /**
    * Send message matching the specifications mentioned in recipientCriteria.
    * 
-   * @param receipientCriteria
+   * @param receipientCriteria criteria to be met, defined as {@link Criteria}
    * @See Criteria
    * @param message
    *          message to be sent. Some attributes of this message will be
    *          changed as required
-   * @return returns how many messages were successfully sent.
+   * @return the number of messages that were successfully sent.
    */
   int send(Criteria recipientCriteria, Message message);
 
   /**
    * This will send the message to all instances matching the criteria<br>
-   * When there is a reply to the message sent AsynCallback.onReply will be
+   * When there is a reply to the message sent AsyncCallback.onReply will be
    * invoked. Application can specify a timeout on AsyncCallback. After every
    * reply is processed AsyncCallback.isDone will be invoked.<br>
    * This method will return after sending the messages. <br>
    * This is useful when message need to be sent and current thread need not
    * wait for response since processing will be done in another thread.
-   * 
+   *
+   * @see #send(Criteria, Message)
    * @param receipientCriteria
    * @param message
-   * @param callbackOnReply
-   * @param timeOut
-   * @param retryCount
-   * @return
+   * @param callbackOnReply callback to trigger on completion
+   * @param timeOut Time to wait before failing the send
+   * @return the number of messages that were successfully sent
    */
   int send(Criteria receipientCriteria, Message message,
       AsyncCallback callbackOnReply, int timeOut);
 
+  /**
+   * @see #send(Criteria, Message, AsyncCallback, int)
+   * @param receipientCriteria
+   * @param message
+   * @param callbackOnReply
+   * @param timeOut
+   * @param retryCount maximum number of times to retry the send
+   * @return the number of messages that were successfully sent
+   */
   int send(Criteria receipientCriteria, Message message,
       AsyncCallback callbackOnReply, int timeOut, int retryCount);
 
@@ -81,17 +90,27 @@ public interface ClusterMessagingService
    * for response. <br>
    * The current thread can use callbackOnReply instance to store application
    * specific data.
-   * 
+   *
+   * @see #send(Criteria, Message, AsyncCallback, int)
    * @param receipientCriteria
    * @param message
    * @param callbackOnReply
    * @param timeOut
    * @param retryCount
-   * @return
+   * @return the number of messages that were successfully sent
    */
   int sendAndWait(Criteria receipientCriteria, Message message,
       AsyncCallback callbackOnReply, int timeOut);
 
+  /**
+   * @see #send(Criteria, Message, AsyncCallback, int, int)
+   * @param receipientCriteria
+   * @param message
+   * @param callbackOnReply
+   * @param timeOut
+   * @param retryCount
+   * @return the number of messages that were successfully sent
+   */
   int sendAndWait(Criteria receipientCriteria, Message message,
       AsyncCallback callbackOnReply, int timeOut, int retryCount);
 
@@ -111,8 +130,7 @@ public interface ClusterMessagingService
    * @param factory
    *          The per-type message factory
    * @param threadpoolSize
-   *        size of the execution threadpool that handles the message 
-   * @return
+   *        size of the execution threadpool that handles the message
    */
   public void registerMessageHandlerFactory(String type,
       MessageHandlerFactory factory);
@@ -121,9 +139,9 @@ public interface ClusterMessagingService
    * This will generate all messages to be sent given the recipientCriteria and MessageTemplate,
    * the messages are not sent.
    * 
-   * @param receipientCriteria
-   * @param messageTemplate
-   * @return
+   * @param receipientCriteria criteria to be met, defined as {@link Criteria}
+   * @param messageTemplate the Message on which to base the messages to send
+   * @return messages to be sent, grouped by the type of instance to send the message to
    */
   public Map<InstanceType, List<Message>> generateMessage(final Criteria recipientCriteria,
       final Message messageTemplate);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java b/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
index c1afb8d..d3de9eb 100644
--- a/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
@@ -35,7 +35,10 @@ import org.apache.helix.manager.zk.ZkClient;
 import org.apache.helix.util.StringTemplate;
 import org.apache.log4j.Logger;
 
-
+/**
+ * Provides access to the persistent configuration of the cluster, the instances that live on it,
+ * and the logical resources assigned to it.
+ */
 public class ConfigAccessor
 {
   private static Logger               LOG      = Logger.getLogger(ConfigAccessor.class);
@@ -69,6 +72,10 @@ public class ConfigAccessor
 
   private final ZkClient              zkClient;
 
+  /**
+   * Initialize an accessor with a Zookeeper client
+   * @param zkClient
+   */
   public ConfigAccessor(ZkClient zkClient)
   {
     this.zkClient = zkClient;
@@ -146,11 +153,12 @@ public class ConfigAccessor
   }
 
   /**
-   * get config
+   * get a single config entry
    *
-   * @param scope
-   * @param key
-   * @return
+   * @param scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param key the identifier of the configuration entry
+   * @return the configuration entry
    */
   public String get(HelixConfigScope scope, String key) {
     Map<String, String> map = get(scope, Arrays.asList(key));
@@ -161,11 +169,12 @@ public class ConfigAccessor
   }
 
   /**
-   * get configs
+   * get many config entries
    *
-   * @param scope
-   * @param keys
-   * @return
+   * @param scope scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param keys the identifiers of the configuration entries
+   * @return the configuration entries, organized by key
    */
   public Map<String, String> get(HelixConfigScope scope, List<String> keys) {
     if (scope == null || scope.getType()== null || !scope.isFullKey()) {
@@ -284,11 +293,12 @@ public class ConfigAccessor
   }
 
   /**
-   * set config. create if not exist
+   * Set config, creating it if it doesn't exist
    *
-   * @param scope
-   * @param key
-   * @param value
+   * @param scope scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param key the identifier of the configuration entry
+   * @param value the configuration
    */
   public void set(HelixConfigScope scope, String key, String value) {
     Map<String, String> map = new TreeMap<String, String>();
@@ -297,10 +307,11 @@ public class ConfigAccessor
   }
 
   /**
-   * set configs. create if not exist
+   * Set multiple configs, creating them if they don't exist
    *
-   * @param scope
-   * @param keyValueMap
+   * @param scope scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param keyValueMap configurations organized by their identifiers
    */
   public void set(HelixConfigScope scope, Map<String, String> keyValueMap)
   {
@@ -398,20 +409,22 @@ public class ConfigAccessor
   }
 
   /**
-   * rmeove config
+   * Remove a single config
    *
-   * @param scope
-   * @param key
+   * @param scope scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param key the identifier of the configuration entry
    */
   public void remove(HelixConfigScope scope, String key) {
     remove(scope, Arrays.asList(key));
   }
 
   /**
-   * remove configs
+   * Remove multiple configs
    *
-   * @param scope
-   * @param keys
+   * @param scope scope specification of the entity set to query
+   *    (e.g. cluster, resource, participant, etc.)
+   * @param keys the identifiers of the configuration entries
    */
   public void remove(HelixConfigScope scope, List<String> keys)
   {
@@ -520,10 +533,10 @@ public class ConfigAccessor
 
 
   /**
-   * get list of config keys for a scope
+   * Get list of config keys for a scope
    *
    * @param scope
-   * @return
+   * @return a list of configuration keys
    */
   public List<String> getKeys(HelixConfigScope scope) {
     if (scope == null || scope.getType() == null) {

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java b/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
index b27596d..104f0bc 100644
--- a/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
@@ -19,12 +19,15 @@ package org.apache.helix;
  * under the License.
  */
 
+/**
+ * Interface to implement to respond to controller changes.
+ */
 public interface ControllerChangeListener
 {
   /**
    * Invoked when controller changes
    * 
-   * @param changeContext
+   * @param changeContext description of the event and state
    */
   public void onControllerChange(NotificationContext changeContext);
 }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/Criteria.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/Criteria.java b/helix-core/src/main/java/org/apache/helix/Criteria.java
index 11e9f7a..101420c 100644
--- a/helix-core/src/main/java/org/apache/helix/Criteria.java
+++ b/helix-core/src/main/java/org/apache/helix/Criteria.java
@@ -19,6 +19,9 @@ package org.apache.helix;
  * under the License.
  */
 
+/**
+ * Describes various properties that operations involving {@link Message} delivery will follow.
+ */
 public class Criteria
 {
   public enum DataSource
@@ -61,87 +64,153 @@ public class Criteria
    * Determine if use external view or ideal state as source of truth
    */
   DataSource _dataSource = DataSource.EXTERNALVIEW;
-  
+
+  /**
+   * Get the current source of truth
+   * @return either the ideal state or the external view
+   */
   public DataSource getDataSource()
   {
     return _dataSource;
   }
-  
+
+  /**
+   * Set the current source of truth
+   * @param source ideal state or external view
+   */
   public void setDataSource(DataSource source)
   {
     _dataSource = source;
   }
 
+  /**
+   * Determine if the message is excluded from being sent to the sender
+   * @return true if the self-sent message is excluded, false otherwise
+   */
   public boolean isSelfExcluded()
   {
     return selfExcluded;
   }
 
+  /**
+   * Indicate whether or not the sender will be excluded as a message recipient
+   * @param selfExcluded true if the sender should be excluded, false otherwise
+   */
   public void setSelfExcluded(boolean selfExcluded)
   {
     this.selfExcluded = selfExcluded;
   }
 
+  /**
+   * Determine the type of the recipient
+   * @return InstanceType (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
+   */
   public InstanceType getRecipientInstanceType()
   {
     return recipientInstanceType;
   }
 
+  /**
+   * Set the type of the recipient
+   * @param recipientInstanceType InstanceType (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
+   */
   public void setRecipientInstanceType(InstanceType recipientInstanceType)
   {
     this.recipientInstanceType = recipientInstanceType;
   }
 
+  /**
+   * Determine if this message should be processed only if an instance was up at send time
+   * @return true if the message will be processed by current live nodes, false otherwise
+   */
   public boolean isSessionSpecific()
   {
     return sessionSpecific;
   }
 
+  /**
+   * Indicate whether or not a message should be restricted to a session
+   * @param sessionSpecific true if the message can only be processed by live nodes at send time,
+   *    false otherwise
+   */
   public void setSessionSpecific(boolean sessionSpecific)
   {
     this.sessionSpecific = sessionSpecific;
   }
 
+  /**
+   * Get the name of the destination instance, available only for PARTICIPANT
+   * @return the instance name
+   */
   public String getInstanceName()
   {
     return instanceName;
   }
 
+  /**
+   * Set the name of the destination instance (PARTICIPANT only)
+   * @param instanceName the instance name or * for all instances
+   */
   public void setInstanceName(String instanceName)
   {
     this.instanceName = instanceName;
   }
 
+  /**
+   * Get the destination resource name
+   * @return destination resource name
+   */
   public String getResource()
   {
     return resourceName;
   }
 
+  /**
+   * Set the destination resource name
+   * @param resourceName the resource name or * for all resources
+   */
   public void setResource(String resourceName)
   {
     this.resourceName = resourceName;
   }
 
+  /**
+   * Get the destination partition name
+   * @return destination partition name
+   */
   public String getPartition()
   {
     return partitionName;
   }
 
+  /**
+   * Set the destination partition name
+   * @param partitionName the partition name, or * for all partitions of a resource
+   */
   public void setPartition(String partitionName)
   {
     this.partitionName = partitionName;
   }
 
+  /**
+   * Get the state of a resource partition
+   * @return the state of the resource partition
+   */
   public String getPartitionState()
   {
     return partitionState;
   }
 
+  /**
+   * Set the state of the resource partition
+   * @param partitionState the state of the resource partition
+   */
   public void setPartitionState(String partitionState)
   {
     this.partitionState = partitionState;
   }
 
+  @Override
   public String toString()
   {
     StringBuilder sb = new StringBuilder();

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
index 0c3baa5..d244600 100644
--- a/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
@@ -23,16 +23,18 @@ import java.util.List;
 
 import org.apache.helix.model.CurrentState;
 
-
+/**
+ * Interface to implement to respond to changes in the current state
+ */
 public interface CurrentStateChangeListener
 {
 
   /**
    * Invoked when current state changes
    * 
-   * @param instanceName
-   * @param statesInfo
-   * @param changeContext
+   * @param instanceName name of the instance whose state changed
+   * @param statesInfo a list of the current states
+   * @param changeContext the change event and state
    */
   public void onStateChange(String instanceName,
                             List<CurrentState> statesInfo,

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ExternalCommand.java b/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
index 5c9d716..b24085d 100644
--- a/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
+++ b/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
@@ -33,6 +33,10 @@ import java.util.concurrent.TimeoutException;
 
 import org.apache.log4j.Logger;
 
+/**
+ * Wrapper for running commands outside of the JVM
+ * @see {@link Process}
+ */
 public class ExternalCommand
 {
   public static final String MODULE = ExternalCommand.class.getName();
@@ -44,6 +48,9 @@ public class ExternalCommand
   private InputReader _out;
   private InputReader _err;
 
+  /**
+   * Stream redirector
+   */
   private static class InputReader extends Thread
   {
     private static final int BUFFER_SIZE = 2048;
@@ -87,7 +94,9 @@ public class ExternalCommand
     }
   }
   /**
-* Constructor */
+   * Initialize with a {@link ProcessBuilder}
+   * @param processBuilder initialized {@link ProcessBuilder} object
+   */
   public ExternalCommand(ProcessBuilder processBuilder)
   {
     _processBuilder = processBuilder;
@@ -109,7 +118,7 @@ public class ExternalCommand
   }
 
   /**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#environment()}
 */
   public Map<String, String> getEnvironment()
   {
@@ -117,7 +126,7 @@ public class ExternalCommand
   }
 
   /**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#directory()}
 */
   public File getWorkingDirectory()
   {
@@ -125,7 +134,7 @@ public class ExternalCommand
   }
 
   /**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#directory(File)}
 */
   public void setWorkingDirectory(File directory)
   {
@@ -133,7 +142,7 @@ public class ExternalCommand
   }
 
   /**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#redirectErrorStream()}
 */
   public boolean getRedirectErrorStream()
   {
@@ -141,19 +150,29 @@ public class ExternalCommand
   }
 
   /**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#redirectErrorStream(boolean)}
 */
   public void setRedirectErrorStream(boolean redirectErrorStream)
   {
     _processBuilder.redirectErrorStream(redirectErrorStream);
   }
 
+  /**
+   * Get the contents of the output stream after completion
+   * @return bytes from the output stream
+   * @throws InterruptedException the process was interrupted before completion
+   */
   public byte[] getOutput() throws InterruptedException
   {
     waitFor();
     return _out.getOutput();
   }
 
+  /**
+   * Get the contents of the error stream after completion
+   * @return bytes from the error stream
+   * @throws InterruptedException the process was interrupted before completion
+   */
   public byte[] getError() throws InterruptedException
   {
     waitFor();
@@ -163,10 +182,10 @@ public class ExternalCommand
   /**
 * Returns the output as a string.
 *
-* @param encoding
+* @param encoding string encoding scheme, e.g. "UTF-8"
 * @return encoded string
-* @throws InterruptedException
-* @throws UnsupportedEncodingException
+* @throws InterruptedException the process was interrupted before completion
+* @throws UnsupportedEncodingException the encoding scheme is invalid
 */
   public String getStringOutput(String encoding) throws InterruptedException,
                                                         UnsupportedEncodingException
@@ -178,7 +197,7 @@ public class ExternalCommand
 * Returns the output as a string. Uses encoding "UTF-8".
 *
 * @return utf8 encoded string
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
 */
   public String getStringOutput() throws InterruptedException
   {
@@ -196,10 +215,10 @@ public class ExternalCommand
   /**
 * Returns the error as a string.
 *
-* @param encoding
+* @param encoding the encoding scheme, e.g. "UTF-8"
 * @return error as string
-* @throws InterruptedException
-* @throws UnsupportedEncodingException
+* @throws InterruptedException the process was interrupted before completion
+* @throws UnsupportedEncodingException the encoding scheme is invalid
 */
   public String getStringError(String encoding) throws InterruptedException,
                                                        UnsupportedEncodingException
@@ -211,7 +230,7 @@ public class ExternalCommand
 * Returns the error as a string. Uses encoding "UTF-8".
 *
 * @return error as string
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
 */
   public String getStringError() throws InterruptedException
   {
@@ -232,7 +251,7 @@ public class ExternalCommand
 * wait for the process to be finished.
 * @return the status code of the process.
 *
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
 */
   public int waitFor() throws InterruptedException
   {
@@ -252,8 +271,8 @@ public class ExternalCommand
 * {@link TimeoutException}
 * @return the status code of the process.
 *
-* @throws TimeoutException
-* @throws InterruptedException
+* @throws TimeoutException the process timed out
+* @throws InterruptedException the process was interrupted before completion
 */
   public int waitFor(long timeout) throws InterruptedException, TimeoutException
   {
@@ -275,6 +294,10 @@ public class ExternalCommand
     return _process.waitFor();
   }
 
+  /**
+   * @see {@link Process#exitValue()}
+   * @return the return code of the process
+   */
   public int exitValue()
   {
     if(_process == null)
@@ -283,6 +306,9 @@ public class ExternalCommand
     return _process.exitValue();
   }
 
+  /**
+   * see {@link Process#destroy()}
+   */
   public void destroy()
   {
     if(_process == null)

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java b/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
index 1fa0db0..9aff2da 100644
--- a/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
@@ -23,15 +23,17 @@ import java.util.List;
 
 import org.apache.helix.model.ExternalView;
 
-
+/**
+ * Interface to implement to be notified of changes to the external view
+ */
 public interface ExternalViewChangeListener
 {
 
   /**
    * Invoked when external view changes
    * 
-   * @param externalViewList
-   * @param changeContext
+   * @param externalViewList a list of ExternalViews
+   * @param changeContext the change event and state
    */
   public void onExternalViewChange(List<ExternalView> externalViewList,
                                    NotificationContext changeContext);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/GroupCommit.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/GroupCommit.java b/helix-core/src/main/java/org/apache/helix/GroupCommit.java
index 29f7369..f90ec9d 100644
--- a/helix-core/src/main/java/org/apache/helix/GroupCommit.java
+++ b/helix-core/src/main/java/org/apache/helix/GroupCommit.java
@@ -29,6 +29,9 @@ import org.I0Itec.zkclient.exception.ZkNoNodeException;
 import org.apache.log4j.Logger;
 
 // TODO: move to mananger.zk
+/**
+ * Support committing updates to data such that they are ordered for each key
+ */
 public class GroupCommit
 { 
   private static Logger  LOG = Logger.getLogger(GroupCommit.class);
@@ -57,7 +60,9 @@ public class GroupCommit
   // TODO: move the cache logic to data accessor
 //  private final Map<String, ZNRecord> _cache  = new ConcurrentHashMap<String, ZNRecord>();
 
-  
+  /**
+   * Set up a group committer and its associated queues
+   */
   public GroupCommit()
   {
     // Don't use Arrays.fill();
@@ -72,6 +77,14 @@ public class GroupCommit
     return _queues[(key.hashCode() & Integer.MAX_VALUE) % _queues.length];
   }
 
+  /**
+   * Do a group update for data associated with a given key
+   * @param accessor accessor with the ability to pull from the current data
+   * @param options see {@link AccessOption}
+   * @param key the data identifier
+   * @param record the data to be merged in
+   * @return true if successful, false otherwise
+   */
   public boolean commit(BaseDataAccessor<ZNRecord> accessor, int options, String key, ZNRecord record)
   {
     Queue queue = getQueue(key);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
index bd3ef4f..607d5c9 100644
--- a/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
@@ -22,18 +22,19 @@ package org.apache.helix;
 import java.util.List;
 
 import org.apache.helix.model.HealthStat;
-import org.apache.helix.model.Message;
-
 
+/**
+ * Interface to implement to listen for when a health status event is triggered.
+ */
 public interface HealthStateChangeListener
 {
 
   /**
    * Invoked when health stats change
    * 
-   * @param instanceName
-   * @param reports
-   * @param changeContext
+   * @param instanceName the instance where the health status changed
+   * @param reports the health statuses
+   * @param changeContext event properties and state
    */
   public void onHealthChange(String instanceName,
                              List<HealthStat> reports,

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixAdmin.java b/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
index 5cd9a13..5f92c24 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
@@ -22,19 +22,18 @@ package org.apache.helix;
 import java.io.IOException;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
-
 import org.apache.helix.model.*;
 import org.apache.helix.model.ClusterConstraints.ConstraintType;
-import org.apache.helix.model.HelixConfigScope.ConfigScopeProperty;
-
 
+/*
+ * Helix cluster management
+ */
 public interface HelixAdmin
 {
   /**
    * Get a list of clusters under "/"
    * 
-   * @return
+   * @return a list of cluster names
    */
   List<String> getClusters();
 
@@ -42,16 +41,16 @@ public interface HelixAdmin
    * Get a list of instances under a cluster
    * 
    * @param clusterName
-   * @return
+   * @return a list of instance names
    */
   List<String> getInstancesInCluster(String clusterName);
 
   /**
-   * Get instance configs
+   * Get an instance config
    * 
    * @param clusterName
    * @param instanceName
-   * @return
+   * @return InstanceConfig corresponding to the specified instance
    */
   InstanceConfig getInstanceConfig(String clusterName, String instanceName);
 
@@ -59,7 +58,7 @@ public interface HelixAdmin
    * Get a list of resources in a cluster
    * 
    * @param clusterName
-   * @return
+   * @return a list of resource names in the cluster
    */
   List<String> getResourcesInCluster(String clusterName);
 
@@ -92,12 +91,12 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param resourceName
-   * @param numResources
+   * @param numPartitions
    * @param stateModelRef
    */
   void addResource(String clusterName,
                    String resourceName,
-                   int numResources,
+                   int numPartitions,
                    String stateModelRef);
   /**
    * 
@@ -114,13 +113,13 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param resourceName
-   * @param numResources
+   * @param numPartitions
    * @param stateModelRef
    * @param idealStateMode
    */
   void addResource(String clusterName,
                    String resourceName,
-                   int numResources,
+                   int numPartitions,
                    String stateModelRef,
                    String idealStateMode);
 
@@ -129,14 +128,14 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param resourceName
-   * @param numResources
+   * @param numPartitions
    * @param stateModelRef
    * @param idealStateMode
    * @param bucketSize
    */
   void addResource(String clusterName,
                    String resourceName,
-                   int numResources,
+                   int numPartitions,
                    String stateModelRef,
                    String idealStateMode,
                    int bucketSize);
@@ -146,7 +145,7 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param resourceName
-   * @param numResources
+   * @param numPartitions
    * @param stateModelRef
    * @param idealStateMode
    * @param bucketSize
@@ -154,7 +153,7 @@ public interface HelixAdmin
    */
   void addResource(String clusterName,
                    String resourceName,
-                   int numResources,
+                   int numPartitions,
                    String stateModelRef,
                    String idealStateMode,
                    int bucketSize,
@@ -296,7 +295,7 @@ public interface HelixAdmin
   void addAlert(String clusterName, String alertName);
 
   /**
-   * Drop a statistics from a cluster
+   * Drop statistics from a cluster
    * 
    * @param clusterName
    * @param statName
@@ -324,7 +323,7 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param stateModelName
-   * @return
+   * @return StateModelDefinition identified by stateModelName
    */
   StateModelDefinition getStateModelDef(String clusterName, String stateModelName);
 
@@ -333,7 +332,7 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param resourceName
-   * @return
+   * @return ExternalView for the resource
    */
   ExternalView getResourceExternalView(String clusterName, String resourceName);
 
@@ -365,7 +364,7 @@ public interface HelixAdmin
    * 
    * @param scope
    * @param keys
-   * @return
+   * @return configuration values ordered by the provided keys
    */
   Map<String, String> getConfig(HelixConfigScope scope, List<String> keys);
 
@@ -373,7 +372,7 @@ public interface HelixAdmin
    * Get configuration keys
    * 
    * @param scope
-   * @return
+   * @return keys mapping to valid configuration values
    */
   List<String> getConfigKeys(HelixConfigScope scope);
 
@@ -402,7 +401,7 @@ public interface HelixAdmin
    * @param clusterName
    * @param stateModelDefName
    * @param stateModelDefFile
-   * @throws IOException
+   * @throws IOException error reading the state model definition file
    */
   void addStateModelDef(String clusterName,
                         String stateModelDefName,
@@ -437,7 +436,7 @@ public interface HelixAdmin
    * 
    * @param clusterName
    * @param constraintType
-   * @return
+   * @return constraints of constraintType
    */
   ClusterConstraints getConstraints(String clusterName,
                                     ConstraintType constraintType);
@@ -447,7 +446,6 @@ public interface HelixAdmin
    * @param clusterName
    * @param currentIdealState
    * @param instanceNames
-   * @return
    */
   void rebalance(String clusterName, 
                        IdealState currentIdealState,
@@ -467,6 +465,7 @@ public interface HelixAdmin
    * @param resourceName
    * @param replica
    * @param keyPrefix
+   * @param group the group identifier of instances to rebalance
    */
   void rebalance(String clusterName, String resourceName, int replica,
       String keyPrefix, String group);
@@ -482,7 +481,6 @@ public interface HelixAdmin
    * @param clusterName
    * @param instanceNames
    * @param tag
-   * @return
    */
   void addInstanceTag(String clusterName, String instanceName, String tag);
   
@@ -491,7 +489,6 @@ public interface HelixAdmin
    * @param clusterName
    * @param instanceNames
    * @param tag
-   * @return
    */
   void removeInstanceTag(String clusterName, String instanceName, String tag);
   

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixConstants.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixConstants.java b/helix-core/src/main/java/org/apache/helix/HelixConstants.java
index 19bc740..f8fded8 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixConstants.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixConstants.java
@@ -19,6 +19,9 @@ package org.apache.helix;
  * under the License.
  */
 
+/*
+ * Identifying constants of the components in a Helix-managed cluster
+ */
 public interface HelixConstants
 {
   // TODO: ChangeType and PropertyType are duplicated, consider unifying

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java b/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
index 946787a..5ad48ea 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
@@ -115,7 +115,7 @@ public interface HelixDataAccessor
    * of the HelixProperty
    * 
    * @param key
-   * @return
+   * @return a map of property identifiers to typed properties
    */
 
   <T extends HelixProperty> Map<String, T> getChildValuesMap(PropertyKey key);
@@ -125,7 +125,7 @@ public interface HelixDataAccessor
    * 
    * @param keys
    * @param children
-   * @return
+   * @return array where true means the child was added and false means it was not
    */
   <T extends HelixProperty> boolean[] createChildren(List<PropertyKey> keys,
       List<T> children);
@@ -135,6 +135,7 @@ public interface HelixDataAccessor
    * 
    * @param keys
    * @param children
+   * @return array where true means the child was set and false means it was not
    */
   <T extends HelixProperty> boolean[] setChildren(List<PropertyKey> keys, List<T> children);
   
@@ -144,6 +145,7 @@ public interface HelixDataAccessor
    * 
    * @param paths
    * @param updaters
+   * @return array where true means the child was updated and false means it was not
    */
   <T extends HelixProperty> boolean[] updateChildren(List<String> paths,
       List<DataUpdater<ZNRecord>> updaters,
@@ -152,14 +154,14 @@ public interface HelixDataAccessor
   /**
    * Get key builder for the accessor
    * 
-   * @return
+   * @return instantiated PropertyKey.Builder
    */
   PropertyKey.Builder keyBuilder();
 
   /**
    * Get underlying base data accessor
    * 
-   * @return
+   * @return a data accessor that can process ZNRecord objects
    */
   BaseDataAccessor<ZNRecord> getBaseDataAccessor();
 }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixException.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixException.java b/helix-core/src/main/java/org/apache/helix/HelixException.java
index 79c3468..0a64194 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixException.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixException.java
@@ -19,10 +19,14 @@ package org.apache.helix;
  * under the License.
  */
 
-
+/**
+ * Base class for an exception thrown by Helix due to inconsistencies caught by Helix itself.
+ */
 public class HelixException extends RuntimeException
 {
 
+  private static final long serialVersionUID = 6558251214364526257L;
+
   public HelixException(String message)
   {
     super(message);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManager.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManager.java b/helix-core/src/main/java/org/apache/helix/HelixManager.java
index 7b01f2c..a4e2c55 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManager.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManager.java
@@ -36,7 +36,9 @@ import org.apache.helix.store.zk.ZkHelixPropertyStore;
  * General flow <blockquote>
  * 
  * <pre>
- * manager = HelixManagerFactory.getManagerFor<ROLE>(); ROLE can be participant, spectator or a controller<br/>
+ * manager = HelixManagerFactory.getZKHelixManager(
+ *    clusterName, instanceName, ROLE, zkAddr);
+ *    // ROLE can be participant, spectator or a controller<br/>
  * manager.connect();
  * manager.addSOMEListener();
  * manager.start()
@@ -50,9 +52,9 @@ import org.apache.helix.store.zk.ZkHelixPropertyStore;
  * 
  * </blockquote> Default implementations available
  * 
- * @see HelixStateMachineEngine for participant
- * @see RoutingTableProvider for spectator
- * @see GenericHelixController for controller
+ * @see HelixStateMachineEngine HelixStateMachineEngine for participant
+ * @see RoutingTableProvider RoutingTableProvider for spectator
+ * @see GenericHelixController RoutingTableProvider for controller
  */
 public interface HelixManager
 {
@@ -74,7 +76,7 @@ public interface HelixManager
    * prevent client in doing anything when its disconnected from the cluster.
    * There is no need to invoke connect again if isConnected return false.
    * 
-   * @return
+   * @return true if connected, false otherwise
    */
   boolean isConnected();
 
@@ -177,7 +179,7 @@ public interface HelixManager
    * any cleanup tasks.<br/>
    * 
    * @param listener
-   * @return
+   * @return true if removed successfully, false otherwise
    */
   boolean removeListener(PropertyKey key, Object listener);
   /**
@@ -191,27 +193,29 @@ public interface HelixManager
   /**
    * Get config accessor
    * 
-   * @return
+   * @return ConfigAccessor
    */
   ConfigAccessor getConfigAccessor();
 
   /**
    * Returns the cluster name associated with this cluster manager
    * 
-   * @return
+   * @return the associated cluster name
    */
   String getClusterName();
 
   /**
    * Returns the instanceName used to connect to the cluster
    * 
-   * @return
+   * @return the associated instance name
    */
 
   String getInstanceName();
 
   /**
    * Get the sessionId associated with the connection to cluster data store.
+   *
+   * @return the session identifier
    */
   String getSessionId();
 
@@ -220,40 +224,44 @@ public interface HelixManager
    * be used to check if there was any new notification when previous
    * notification was being processed. This is updated based on the
    * notifications from listeners registered.
+   *
+   * @return UNIX timestamp
    */
   long getLastNotificationTime();
 
   /**
    * Provides admin interface to setup and modify cluster.
    * 
-   * @return
+   * @return instantiated HelixAdmin
    */
   HelixAdmin getClusterManagmentTool();
 
   /**
    * Get property store
    * 
-   * @return
+   * @return the property store that works with ZNRecord objects
    */
   ZkHelixPropertyStore<ZNRecord> getHelixPropertyStore();
 
   /**
    * Messaging service which can be used to send cluster wide messages.
-   * 
+   *
+   * @return messaging service
    */
   ClusterMessagingService getMessagingService();
 
   /**
    * Participant only component that periodically update participant health
    * report to cluster manager server.
-   * 
+   *
+   * @return ParticipantHealthReportCollector
    */
   ParticipantHealthReportCollector getHealthReportCollector();
 
   /**
    * Get cluster manager instance type
    * 
-   * @return
+   * @return instance type (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
    */
   InstanceType getInstanceType();
 
@@ -268,7 +276,7 @@ public interface HelixManager
    * Get helix manager properties read from 
    * helix-core/src/main/resources/cluster-manager.properties 
    * 
-   * @return
+   * @return deserialized properties
    */
   HelixManagerProperties getProperties();
   

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java b/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
index cc5673f..1f39d46 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
@@ -28,20 +28,22 @@ package org.apache.helix;
 import org.apache.helix.manager.zk.ZKHelixManager;
 import org.apache.log4j.Logger;
 
-
+/**
+ * Obtain one of a set of Helix cluster managers, organized by the backing system.
+ */
 public final class HelixManagerFactory
 {
   private static final Logger logger = Logger.getLogger(HelixManagerFactory.class);
 
   /**
-   * Construct a zk-based cluster manager enforce all types (PARTICIPANT, CONTROLLER, and
-   * SPECTATOR to have a name
+   * Construct a zk-based cluster manager that enforces all types (PARTICIPANT, CONTROLLER, and
+   * SPECTATOR) to have a name
    * 
    * @param clusterName
    * @param instanceName
    * @param type
    * @param zkAddr
-   * @return
+   * @return a HelixManager backed by Zookeeper
    */
   public static HelixManager getZKHelixManager(String clusterName,
                                                String instanceName,

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java b/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
index f58dc27..77f6697 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
@@ -20,7 +20,6 @@ package org.apache.helix;
  */
 
 import java.io.InputStream;
-import java.util.Arrays;
 import java.util.Properties;
 
 import org.apache.log4j.Logger;
@@ -37,6 +36,10 @@ public class HelixManagerProperties
   
   private final Properties _properties = new Properties();
 
+  /**
+   * Initialize properties from a file
+   * @param propertyFileName
+   */
   public HelixManagerProperties(String propertyFileName)
   {
     try
@@ -59,14 +62,18 @@ public class HelixManagerProperties
   public HelixManagerProperties() {
     // load empty properties
   }
-  
+
+  /**
+   * Get properties wrapped as {@link Properties}
+   * @return Properties
+   */
   public Properties getProperties() {
     return _properties;
   }
   
   /**
    * get helix version
-   * @return
+   * @return version read from properties
    */
   public String getVersion() {
     return this.getProperty("clustermanager.version");
@@ -76,7 +83,7 @@ public class HelixManagerProperties
    * get property for key
    * 
    * @param key
-   * @return
+   * @return property associated by key
    */
   public String getProperty(String key)
   {
@@ -95,7 +102,7 @@ public class HelixManagerProperties
    * 
    * @param version1
    * @param version2
-   * @return
+   * @return true if version1 >= version2, false otherwise
    */
   static boolean versionNoLessThan(String version1, String version2) {
     if (version1 == null || version2 == null) {
@@ -133,7 +140,7 @@ public class HelixManagerProperties
    * false otherwise
    * 
    * @param participantVersion
-   * @return
+   * @return true if compatible, false otherwise
    */
   public boolean isParticipantCompatible(String participantVersion) {
     return isFeatureSupported("participant", participantVersion);
@@ -145,7 +152,7 @@ public class HelixManagerProperties
    * 
    * @param featureName
    * @param participantVersion
-   * @return
+   * @return true if supported, false otherwise
    */
   public boolean isFeatureSupported(String featureName, String participantVersion) {
     String  minSupportedVersion = getProperty("minimum_supported_version." + featureName);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixProperty.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixProperty.java b/helix-core/src/main/java/org/apache/helix/HelixProperty.java
index 31ac50a..e60c409 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixProperty.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixProperty.java
@@ -40,26 +40,46 @@ public class HelixProperty
 
   protected final ZNRecord _record;
 
+  /**
+   * Initialize the property with an identifier
+   * @param id
+   */
   public HelixProperty(String id)
   {
     _record = new ZNRecord(id);
   }
 
+  /**
+   * Initialize the property with an existing ZNRecord
+   * @param record
+   */
   public HelixProperty(ZNRecord record)
   {
     _record = new ZNRecord(record);
   }
 
+  /**
+   * Get the property identifier
+   * @return the property id
+   */
   public final String getId()
   {
     return _record.getId();
   }
 
+  /**
+   * Get the backing ZNRecord
+   * @return ZNRecord object associated with this property
+   */
   public final ZNRecord getRecord()
   {
     return _record;
   }
 
+  /**
+   * Set the changes to the backing ZNRecord
+   * @param deltaList list of ZNRecord updates to be made
+   */
   public final void setDeltaList(List<ZNRecordDelta> deltaList)
   {
     _record.setDeltaList(deltaList);
@@ -71,6 +91,10 @@ public class HelixProperty
     return _record.toString();
   }
 
+  /**
+   * Get the size of buckets defined
+   * @return the bucket size, or 0 if not defined
+   */
   public int getBucketSize()
   {
     String bucketSizeStr =
@@ -90,6 +114,10 @@ public class HelixProperty
     return bucketSize;
   }
 
+  /**
+   * Set the size of buckets defined
+   * @param bucketSize the bucket size (will default to 0 if negative)
+   */
   public void setBucketSize(int bucketSize)
   {
     if (bucketSize <= 0)
@@ -99,11 +127,11 @@ public class HelixProperty
   }
 
   /**
-   * static method that convert ZNRecord to an instance that subclasses HelixProperty
+   * static method that converts ZNRecord to an instance that subclasses HelixProperty
    * 
-   * @param clazz
-   * @param record
-   * @return
+   * @param clazz subclass of HelixProperty
+   * @param record the ZNRecord describing the property
+   * @return typed instance corresponding to the record, or null if conversion fails
    */
   public static <T extends HelixProperty> T convertToTypedInstance(Class<T> clazz,
                                                                    ZNRecord record)
@@ -127,6 +155,12 @@ public class HelixProperty
     return null;
   }
 
+  /**
+   * Convert a collection of records to typed properties
+   * @param clazz Subclass of HelixProperty
+   * @param records the ZNRecords describing the property
+   * @return list of typed instances for which the conversion succeeded, or null if records is null
+   */
   public static <T extends HelixProperty> List<T> convertToTypedList(Class<T> clazz,
                                                                      Collection<ZNRecord> records)
   {
@@ -147,6 +181,11 @@ public class HelixProperty
     return decorators;
   }
 
+  /**
+   * Converts a list of records to a map of the record identifier to typed properties
+   * @param records the ZNRecords to convert
+   * @return id --> HelixProperty subclass map
+   */
   public static <T extends HelixProperty> Map<String, T> convertListToMap(List<T> records)
   {
     if (records == null)
@@ -162,6 +201,11 @@ public class HelixProperty
     return decorators;
   }
 
+  /**
+   * Convert typed properties to a list of records
+   * @param typedInstances objects subclassing HelixProperty
+   * @return a list of ZNRecord objects
+   */
   public static <T extends HelixProperty> List<ZNRecord> convertToList(List<T> typedInstances)
   {
     if (typedInstances == null)
@@ -178,12 +222,20 @@ public class HelixProperty
     return records;
   }
 
+  /**
+   * Change the state of batch messaging
+   * @param enable true to enable, false to disable
+   */
   public void setBatchMessageMode(boolean enable)
   {
     _record.setSimpleField(HelixPropertyAttribute.BATCH_MESSAGE_MODE.toString(), ""
         + enable);
   }
 
+  /**
+   * Get the state of batch messaging
+   * @return true if enabled, false if disabled
+   */
   public boolean getBatchMessageMode()
   {
     String enableStr =
@@ -202,7 +254,11 @@ public class HelixProperty
       return false;
     }
   }
-  
+
+  /**
+   * Get property validity
+   * @return true if valid, false if invalid
+   */
   public boolean isValid()
   {
     return true;

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java b/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
index 0b7edb9..c975867 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
@@ -19,17 +19,18 @@ package org.apache.helix;
  * under the License.
  */
 
+/**
+ * Interface for defining a generic task to run periodically.
+ */
 public abstract class HelixTimerTask
 {
   /**
-   * Timer task starts
-   * 
+   * Start a timer task
    */
   public abstract void start();
   
   /**
-   * Timer task stops
-   * 
+   * Stop a timer task
    */
   public abstract void stop();
 }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
index d387593..8104811 100644
--- a/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
@@ -23,7 +23,9 @@ import java.util.List;
 
 import org.apache.helix.model.IdealState;
 
-
+/**
+ * Interface to implement to listen for changes to the ideal state of resources.
+ */
 public interface IdealStateChangeListener
 {
 

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java b/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
index 5d55be1..68446fc 100644
--- a/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
@@ -23,6 +23,9 @@ import java.util.List;
 
 import org.apache.helix.model.InstanceConfig;
 
+/**
+ * Interface to implement to listen for changes to instance configurations.
+ */
 public interface InstanceConfigChangeListener 
 {
   /**

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java b/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
index 79b0845..1b85982 100644
--- a/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
@@ -23,7 +23,9 @@ import java.util.List;
 
 import org.apache.helix.model.LiveInstance;
 
-
+/**
+ * Interface to implement to listen for live instance changes.
+ */
 public interface LiveInstanceChangeListener
 {
 

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java b/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
index 1651839..03f6061 100644
--- a/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
+++ b/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
@@ -18,10 +18,13 @@ package org.apache.helix;
  * under the License.
  */
 
+/**
+ * Interface to provide additional information about a live instance at creation time
+ */
 public interface LiveInstanceInfoProvider
 {
   /**
-   * Callback function that is called by HelixManager before it creates LiveInstance Zk Node. 
+   * Callback function that is called by HelixManager before it creates LiveInstance Zk Node.
    * The ZNRecord returned by this function 
    * 
    * @see ZkHelixManager#addLiveInstance()

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/MessageListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/MessageListener.java b/helix-core/src/main/java/org/apache/helix/MessageListener.java
index cb3776e..8b15e5f 100644
--- a/helix-core/src/main/java/org/apache/helix/MessageListener.java
+++ b/helix-core/src/main/java/org/apache/helix/MessageListener.java
@@ -23,7 +23,9 @@ import java.util.List;
 
 import org.apache.helix.model.Message;
 
-
+/**
+ * Interface to implement when there is a change to messages
+ */
 public interface MessageListener
 {
 

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/NotificationContext.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/NotificationContext.java b/helix-core/src/main/java/org/apache/helix/NotificationContext.java
index f683e77..38f8c7b 100644
--- a/helix-core/src/main/java/org/apache/helix/NotificationContext.java
+++ b/helix-core/src/main/java/org/apache/helix/NotificationContext.java
@@ -22,9 +22,14 @@ package org.apache.helix;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Metadata associated with a notification event and the current state of the cluster
+ */
 public class NotificationContext
 {
-	// keys used for object map
+	/**
+	 * keys used for object map
+	 */
 	public enum MapKey {
 		TASK_EXECUTOR,
 		CURRENT_STATE_UPDATE,
@@ -38,72 +43,129 @@ public class NotificationContext
   private String _pathChanged;
   private String _eventName;
 
+  /**
+   * Get the name associated with the event
+   * @return event name
+   */
   public String getEventName()
   {
     return _eventName;
   }
 
+  /**
+   * Set the name associated with the event
+   * @param eventName the event name
+   */
   public void setEventName(String eventName)
   {
     _eventName = eventName;
   }
 
+  /**
+   * Instantiate with a HelixManager
+   * @param manager {@link HelixManager} object
+   */
   public NotificationContext(HelixManager manager)
   {
     _manager = manager;
     _map = new HashMap<String, Object>();
   }
 
+  /**
+   * Get the HelixManager associated with this notification
+   * @return {@link HelixManager} object
+   */
   public HelixManager getManager()
   {
     return _manager;
   }
 
+  /**
+   * Get a map describing the update (keyed on {@link MapKey})
+   * @return the object map describing the update
+   */
   public Map<String, Object> getMap()
   {
     return _map;
   }
 
+  /**
+   * Get the type of the notification
+   * @return the notification type
+   */
   public Type getType()
   {
     return _type;
   }
 
+  /**
+   * Set the HelixManager associated with this notification
+   * @param manager {@link HelixManager} object
+   */
   public void setManager(HelixManager manager)
   {
     this._manager = manager;
   }
 
+  /**
+   * Add notification metadata
+   * @param key String value of a {@link MapKey}
+   * @param value
+   */
   public void add(String key, Object value)
   {
     _map.put(key, value);
   }
 
+  /**
+   * Set the notification map
+   * @param map
+   */
   public void setMap(Map<String, Object> map)
   {
     this._map = map;
   }
 
+  /**
+   * Set the notification type
+   * @param {@link Type} object
+   */
   public void setType(Type type)
   {
     this._type = type;
   }
 
+  /**
+   * Get a notification attribute
+   * @param key String from a {@link MapKey}
+   * @return
+   */
   public Object get(String key)
   {
     return _map.get(key);
   }
 
+  /**
+   * Valid types of notifications
+   */
   public enum Type
   {
     INIT, CALLBACK, FINALIZE
   }
 
+  /**
+   * Get the path changed status
+   * @return String corresponding to the path change
+   */
   public String getPathChanged()
   {
     return _pathChanged;
   }
 
+  /**
+   * Set the path changed status
+   * @param pathChanged
+   */
   public void setPathChanged(String pathChanged)
   {
     this._pathChanged = pathChanged;

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java b/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
index 9d65a14..45da706 100644
--- a/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
+++ b/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
@@ -19,6 +19,9 @@ package org.apache.helix;
  * under the License.
  */
 
+/**
+ * Called to allow definition of tasks prior to connecting to Zookeeper
+ */
 public interface PreConnectCallback
 {
   /**


Mime
View raw message