added more JavaDoc as Josh Shinavier asked questions about the API.

src/main/java/com/tinkerpop/blueprints/pgm/AutomaticIndex.java

@@ -3,7 +3,8 @@
 import java.util.Set;
 
 /**
- * An automatic index will automatically maintain an index of element properties as the element properties mutate.
+ * An automatic index will automatically maintain an index of element properties as element properties mutate.
+ * If an element is removed from the graph, then it is also automatically removed from the automatic index.
  * The key/value pairs that are automatically monitored are element properties and their values.
  *
  * @author Marko A. Rodriguez (http://markorodriguez.com)

src/main/java/com/tinkerpop/blueprints/pgm/Element.java

@@ -47,10 +47,9 @@ public abstract interface Element {
     public Object removeProperty(String key);
 
     /**
-     * An identifier that is unique to its inhereting class.
-     * All vertices of a graph must have unique identifers.
+     * An identifier that is unique to its inheriting class.
+     * All vertices of a graph must have unique identifiers.
      * All edges of a graph must have unique identifiers.
-     * It is areEqual for the two classe instances to share the same address space.
      *
      * @return the identifier of the element
      */

src/main/java/com/tinkerpop/blueprints/pgm/Graph.java

@@ -32,7 +32,7 @@ public interface Graph {
 
     /**
      * Remove the provided vertex from the graph.
-     * Upon removing the vertex, all the edges by which the vertex is associated must be removed as well.
+     * Upon removing the vertex, all the edges by which the vertex is connected will be removed as well.
      *
      * @param vertex the vertex to remove from the graph
      */

src/main/java/com/tinkerpop/blueprints/pgm/IndexableGraph.java

@@ -13,9 +13,9 @@ public interface IndexableGraph extends Graph {
      * Generate an index with a particular name, for a particular class, and of a particular type.
      *
      * @param indexName  the name of the index
-     * @param indexClass the element class that this index is indexing
+     * @param indexClass the element class that this index is indexing (can be base class)
      * @param type       whether the index is a manual or automatic index
-     * @param <T>        the element class that this index is indexing
+     * @param <T>        the element class that this index is indexing (can be base class)
      * @return the index created
      */
     public <T extends Element> Index<T> createIndex(String indexName, Class<T> indexClass, Index.Type type);
@@ -24,8 +24,8 @@ public interface IndexableGraph extends Graph {
      * Get an index from the graph by its name and index class. An index is unique up to name.
      *
      * @param indexName  the name of the index to retrieve
-     * @param indexClass the class of the elements being indexed
-     * @param <T>        the class of the elements being indexed
+     * @param indexClass the class of the elements being indexed (can be base class)
+     * @param <T>        the class of the elements being indexed (can be base class)
      * @return the retrieved index
      */
     public <T extends Element> Index<T> getIndex(String indexName, Class<T> indexClass);