--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/HostRef.java	Wed Jul 31 14:58:11 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/HostRef.java	Wed Jul 31 11:57:54 2013 -0400
@@ -36,11 +36,20 @@
 
 package com.redhat.thermostat.storage.core;
 
+/**
+ * Identifies an agent or a host
+ */
+// See http://icedtea.classpath.org/bugzilla/show_bug.cgi?id=1508 for
+// more information
 public class HostRef implements Ref {
 
     private final String uid;
     private final String name;
 
+    /**
+     * @param id the UUID string that uniquely identifies an agent/host
+     * @param name the host name of an agent/host
+     */
     public HostRef(String id, String name) {
         this.uid = id;
         this.name = name;

--- a/storage/core/src/main/java/com/redhat/thermostat/storage/dao/AgentInfoDAO.java	Wed Jul 31 14:58:11 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/dao/AgentInfoDAO.java	Wed Jul 31 11:57:54 2013 -0400
@@ -45,6 +45,9 @@
 import com.redhat.thermostat.storage.core.Key;
 import com.redhat.thermostat.storage.model.AgentInformation;
 
+/**
+ * Access information about agents that agents publish to storage.
+ */
 @Service
 public interface AgentInfoDAO extends Countable {
 
@@ -60,17 +63,47 @@
             ALIVE_KEY,
             CONFIG_LISTEN_ADDRESS);
 
+    /**
+     * Get information about all known agents.
+     *
+     * @return a {@link List} of {@link AgentInformation} for all agents
+     * who have published their information. Will be empty if there is no
+     * information.
+     */
     List<AgentInformation> getAllAgentInformation();
 
+    /**
+     * Get information about all alive agents.
+     *
+     * @return a {@link List} of {@link AgentInformation} for all alive
+     * agents who have published their information. Will be empty if there
+     * is no information or no alive agents.
+     */
     List<AgentInformation> getAliveAgents();
 
+    /**
+     * Get information about a specific agent.
+     *
+     * @return a {@link AgentInformation} describing information about the agent
+     * indicated by {@code agentRef}. {@code null} if no information about the
+     * agent could be located.
+     */
     AgentInformation getAgentInformation(HostRef agentRef);
 
+    /**
+     * Publish information about agent into the storage.
+     */
     void addAgentInformation(AgentInformation agentInfo);
 
+    /**
+     * Update information about an existing agent. No changes will be performed
+     * if there is no matching agent.
+     */
     void updateAgentInformation(AgentInformation agentInfo);
 
+    /**
+     * Remove information about an agent that was published to storage.
+     */
     void removeAgentInformation(AgentInformation agentInfo);
 
 }
-