Added comments based on the team's discussions of the Type and

webapp/src/main/java/org/apache/hadoop/metadata/web/resources/EntityResource.java

@@ -47,6 +47,9 @@ import java.io.StringWriter;
 
 /**
  * Entity management operations as REST API.
+ * 
+ * An entity is an "instance" of a Type.  Entities conform to the definition
+ * of the Type they correspond with.
  */
 @Path("entities")
 public class EntityResource {

webapp/src/main/java/org/apache/hadoop/metadata/web/resources/MetadataDiscoveryResource.java

@@ -22,6 +22,12 @@ import javax.ws.rs.Path;
 
 /**
  * Jersey Resource for metadata operations.
+ * 
+ * The entry point for all operations against various aspects of the entities graph.
+ * 
+ * For instance,
+ * 	lineage: given an entity, X, get me the lineage - all entities X is derived from (recursively)
+ * 	'search': find entities generated by Hive processes or that were generated by Sqoop, etc.
  */
 @Path("discovery")
 public class MetadataDiscoveryResource {

webapp/src/main/java/org/apache/hadoop/metadata/web/resources/RexsterGraphResource.java

@@ -54,6 +54,9 @@ import java.util.Set;
  * Jersey Resource for lineage metadata operations.
  * Implements most of the GET operations of Rexster API with out the indexes.
  * https://github.com/tinkerpop/rexster/wiki/Basic-REST-API
+ * 
+ * This is a subset of Rexster's REST API, designed to provide only read-only methods
+ * for accessing the backend graph.
  */
 @Path("graph")
 public class RexsterGraphResource {

webapp/src/main/java/org/apache/hadoop/metadata/web/resources/TypesResource.java

@@ -26,6 +26,9 @@ import javax.ws.rs.core.Response;
 
 /**
  * This class provides RESTful API for Types.
+ * 
+ * A type is the description of any representable item;
+ * e.g. a Hive table
  */
 @Path("types")
 public class TypesResource {