diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy
index b6af0dd..9141e50 100644
--- a/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy
+++ b/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy
@@ -21,14 +21,19 @@ import org.apache.tinkerpop.gremlin.structure.Element
 @Slf4j
 class PropertyValuesHolder<T> {
 
-    /** */
+    /** A map of property definitions to property values */
     Map<PropertyDefinition,Object> propertyValues = new HashMap<PropertyDefinition,Object>()
 
-    /** */
+    /** If true, then properties must be defined to have a value */
     Boolean propertiesMustBeDefined = true
 
 
-    /** */
+    /** 
+     * Set the provided property to the provided enum value.
+     * @param propDef The property to set
+     * @param propValue The enum value to use
+     * @return This object
+     */
     public T withProperty(PropertyDefinition propDef, Enum propValue) {
         assert propDef != null
         assert propValue != null
@@ -36,7 +41,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set the provided property to the provided value.
+     * @param propDef The property to set
+     * @param prooValue The value to use
+     * @return This object
+     */
     public T withProperty(PropertyDefinition propDef, Object propValue) {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -51,7 +61,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set the provided property pairs of properties and values, ex.
+     * .setProperty(p1, v1, p2, v2).
+     * @param args Pairs of property definitions and values
+     * @return This object 
+     */
     public T withProperties(Object... args) {
         if (args.size() == 1) {
             assert args[0] instanceof Map
@@ -61,7 +76,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set all the properties specified in the provided map of property 
+     * definitions to values ex. .setProperty([p1:v1, p2:v2]).
+     * @param args Map of property definitions to property values
+     * @return This object
+     */
     public T withProperties(Map args) {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -75,7 +95,13 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set all the properties in the provided list where the list elements
+     * alternate between property definitions and property values ex.
+     * .setProperty([p1, v1, p2, v2]).
+     * @paran args A list of property definitions and values
+     * @return This object
+     */
     public T withProperties(List args) {
         def numArgs = args.size()
         assert numArgs >= 2
@@ -88,13 +114,23 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set the pairs of property definitions and property values when the value
+     * is not null ex. .withNonNullProperties(p1, v1, p2, v2)
+     * @param args Pairs of property definitions and values
+     * @return This object 
+     */
     public T withNonNullProperties(Object... args) {
         withNonNullProperties(args.toList())
     }
 
 
-    /** */
+    /** 
+     * Set the pairs of property definitions and property values when the value
+     * is not null ex. .withNonNullProperties([p1, v1, p2, v2]).
+     * @paran args A list of property definitions and values
+     * @return This object
+     */
     public T withNonNullProperties(List args) {
         def numArgs = args.size()
         assert numArgs >= 2
@@ -110,7 +146,8 @@ class PropertyValuesHolder<T> {
     /** 
      * Matches a map of data against the properties of this element by name and
      * assignes the property value on match.
-     *
+     * @param args A map of property definitions to values
+     * @return This object
      */
     public T withMatchingProperties(Map args) {
         assert args != null
@@ -129,7 +166,8 @@ class PropertyValuesHolder<T> {
      * Matches a map of data against the properties of this element by name and
      * assignes the property value on match ignoring data records where the
      * value is null.
-     *
+     * @param args A map of property definitions to values
+     * @return This object
      */
     public T withNonNullMatchingProperties(Map args) {
         assert args != null
@@ -138,7 +176,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Utility method to split a list of pairs into property definition and
+     * value and then call withProperty on each pair.
+     * @param pairs A list of two element lists where each two element list
+     * is a pair of property definition and property value.
+     */
     private void holdPropertyPairs(List<List> pairs) {
         Map<PropertyDefinition,Object> props = new HashMap<PropertyDefinition,Object>()
         pairs.each { p ->
@@ -152,7 +195,10 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Returns a map of all property definitions and their value.
+     * @return A map of property definition to value
+     */
     public Map<PropertyDefinition,Object> allPropertyValues() {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -172,7 +218,11 @@ class PropertyValuesHolder<T> {
     } 
 
 
-    /** */
+    /** 
+     * Set the properties of the provided graph element to the property values 
+     * held by this object.
+     * @param el The target graph element 
+     */
     public Element setElementProperties(Element el) {
         def pvs = allPropertyValues()
         pvs.each { PropertyDefinition vp, Object val ->
diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy
index 6e9ccf8..13d5bed 100644
--- a/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy
+++ b/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy
@@ -28,8 +28,8 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     ///////////////////////////////////////////////////////////////////////////
 
     /** 
-     * Object that owns this builder.
-     * */
+     * The source vertex definition of this builder.
+     */
     VertexDefinition vertexDef
 
 
@@ -37,7 +37,10 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     // CONSTRUCTOR
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Constructor
+     * @param The source vertex definition of this builder.
+     */
     public VertexBuilder(VertexDefinition vertexDef) {
         assert vertexDef
         this.vertexDef = vertexDef
@@ -48,7 +51,9 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     // GETTERS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Return the source vertex definition as an element definition.
+     */
     public ElementDefinition getElementDef() { vertexDef }
 
 
@@ -104,7 +109,13 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     }
 
 
-    /** */
+    /** 
+     * Returns a graph traversal that starts with vertices that match this
+     * vertex builder.
+     * @param graph The property graph
+     * @param g A graph traversal source to use
+     * @return A graph traversal
+     */
     public Traversal traversal(Graph graph, GraphTraversalSource g) {
         assert graph
         assert g
@@ -174,7 +185,10 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     }
 
 
-    /** */
+    /** 
+     * Assert that all the properties required by the source vertex definition
+     * have been set in this builder.
+     */
     void assertRequiredProperties() {
         vertexDef.requiredProperties.each { requiredPropDef ->
             boolean found = allPropertyValues().find { k, v ->
diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/VertexDefinition.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/VertexDefinition.groovy
index b6d0d8e..d57d8fa 100644
--- a/app/carnival-graph/src/main/groovy/carnival/graph/VertexDefinition.groovy
+++ b/app/carnival-graph/src/main/groovy/carnival/graph/VertexDefinition.groovy
@@ -75,18 +75,30 @@ trait VertexDefinition extends ElementDefinition {
     // GETTERS / SETTERS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** Setter wrapper for propertyDefs */
+    /** 
+     * Getter wrapper for propertyDefs 
+     * @return A set of property definitions
+     */
     Set<PropertyDefinition> getVertexProperties() { this.propertyDefs }
     
-    /** Getter wrapper for propertyDefs */
+    /** 
+     * Setter wrapper for propertyDefs 
+     * @param A set of proeprty definitions
+     */
     void setVertexProperties(Set<PropertyDefinition> propertyDefs) {
         this.propertyDefs = propertyDefs
     }
 
-    /** */
+    /** 
+     * Get the superclass vertex definition of this vertex definition.
+     * @return The superclass vertex definition
+     */
     VertexDefinition getSuperClass() { this.superClass }
 
-    /** */
+    /** 
+     * Set the superclass vertex definition of this vertex definition.
+     * @param vDef The superclass vertex definition
+     */
     void setSuperClass(VertexDefinition vDef) {
         assert vDef != null
         if (!isClass()) throw new RuntimeException("cannot set superClass when isClass() is false")
@@ -94,10 +106,17 @@ trait VertexDefinition extends ElementDefinition {
         this.superClass = vDef
     }
 
-    /** */
+    /** 
+     * Return the vertex definition of which this definition is an instance.
+     * @return The instanceOf vertex definition
+     */
     VertexDefinition getInstanceOf() { this.instanceOf }
 
-    /** */
+    /** 
+     * Set the vertex definition of which this definition is an instance; 
+     * applies only to vertex definitions that do not define classes.
+     * @param vDef The instanceOf vertex definition
+     */
     void setInstanceOf(VertexDefinition vDef) {
         assert vDef != null
         if (isClass()) throw new RuntimeException("cannot set instanceOf when isClass() is true")
@@ -111,7 +130,10 @@ trait VertexDefinition extends ElementDefinition {
     // PROPERTY METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Return the string label to use for instantiated vertices.
+     * @return The string label
+     */
     public String getLabel() {
         def n = name()
         def chunks = n.split(NAME_SEPARATOR)
@@ -121,27 +143,42 @@ trait VertexDefinition extends ElementDefinition {
     }
 
 
-    /** */
+    /** 
+     * Return true if the provided vertex has the label of this vertex 
+     * definition.
+     * @param v The vertex to test
+     */
     public boolean hasLabel(Vertex v) {
         assert v != null
         return v.label() == getLabel()
     }
 
 
-    /** */
+    /** 
+     * Synonym for isClass()
+     * @see #isClass()
+     */
     boolean getIsClass() {
         isClass()        
     }
 
 
-    /** */
+    /** 
+     * Return true if this definition defines a class vertex.
+     * @return A boolean value
+     */
     public boolean isClass() {
         if (this.isClass != null) return this.isClass
         name().toLowerCase().endsWith(CLASS_SUFFIX)
     }
 
 
-    /** */
+    /** 
+     * Return all the vertex properties of the provided vertex that are
+     * defined in this vertex definition.
+     * @param v The source vertex
+     * @return A set of vertex properties
+     */
     public Set<VertexProperty> definedPropertiesOf(Vertex v) {
         Set<VertexProperty> vProps = new HashSet<VertexProperty>()
         propertyDefs.each { pDef ->
@@ -159,7 +196,10 @@ trait VertexDefinition extends ElementDefinition {
     // SINGLETON VERTEX METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Create a vertex builder using this vertex definition as a source.
+     * @return A vertex builder
+     */
     public VertexBuilder instance() {
         def vb = new VertexBuilder(this)
         vb.propertiesMustBeDefined = this.propertiesMustBeDefined
@@ -167,7 +207,12 @@ trait VertexDefinition extends ElementDefinition {
     }
 
 
-    /** */
+    /** 
+     * Create a vertex using this vertex definition with no properties set in
+     * the provided property graph.
+     * @param graph The target property graph
+     * @return The created vertex
+     */
     public Vertex createVertex(Graph graph) {
         assert graph
         if (isClass()) throw new RuntimeException("cannot create instance vertex of class ${this}")
@@ -191,13 +236,23 @@ trait VertexDefinition extends ElementDefinition {
     // TYPE CHECKING
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Always returns false since edges cannot be defined by vertex 
+     * definitions.
+     * @param e The edge to test
+     * @return false
+     */
     public boolean isa(Edge e) {
         assert e != null
         return false
     }
 
-    /** */
+    /** 
+     * Return true if the provided vertex matches this vertex definition; this
+     * method does not take properties into account.
+     * @param v The vertex to test
+     * @return True if the provided vertex matches this vertex definition
+     */
     public boolean isa(Vertex v) {
         assert v != null
         (v.label() == getLabel() && Base.PX.NAME_SPACE._valueOf(v) == getNameSpace())
@@ -208,7 +263,12 @@ trait VertexDefinition extends ElementDefinition {
     // KNOWLEDGE GRAPH METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Create the class level vertices in the provided graph using the provided
+     * graph traversal source.
+     * @param graph The target property graph
+     * @param g The graph traversal source to use
+     */
     public void applyTo(Graph graph, GraphTraversalSource g) {
         if (this.isClass() && this.requiredProperties.size() == 0) {
             this.vertex = this.instance().ensure(graph, g)
@@ -225,8 +285,10 @@ trait VertexDefinition extends ElementDefinition {
 
 
     /** 
-     *
-     *
+     * Sets that this definition is a subclass of the provided superclass 
+     * definition using the provided graph traversal source.
+     * @param g The graph graversal source to use
+     * @param superClassDef The superclass definition
      */
     public void setSubclassOf(GraphTraversalSource g, VertexDefinition superClassDef) {
         assert g
@@ -243,8 +305,10 @@ trait VertexDefinition extends ElementDefinition {
 
 
     /** 
-     *
-     *
+     * Sets that this definition is a superclass of the provided subclass
+     * definition using the provided graph traversal source.
+     * @param g The graph traversal source to use
+     * @param subclassV The subclass vertex.
      */
     public void setSuperclassOf(GraphTraversalSource g, Vertex subclassV) {
         assert g
@@ -260,8 +324,12 @@ trait VertexDefinition extends ElementDefinition {
 
 
     /** 
-     *
-     *
+     * If not already present, create an edge based on the provided edge
+     * definition between the singleton vertex of this vertex definition and
+     * the singleton vertex of the provided target class definition.
+     * @param g The graph traversal source to use
+     * @param rel The edge definition
+     * @param targetClassDef The target class definition
      */
     public void setRelationship(GraphTraversalSource g, EdgeDefinition rel, VertexDefinition targetClassDef) {
         //log.debug "setRelationship rel:$rel"
@@ -284,8 +352,8 @@ trait VertexDefinition extends ElementDefinition {
     ///////////////////////////////////////////////////////////////////////////
 
     /**
-     *
-     *
+     * Return a string representation of this object.
+     * @return A string
      */
     public String toString() {
         def str = "${name()} ${nameSpace}"
diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/WithPropertyDefsTrait.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/WithPropertyDefsTrait.groovy
index fc902b7..b018347 100644
--- a/app/carnival-graph/src/main/groovy/carnival/graph/WithPropertyDefsTrait.groovy
+++ b/app/carnival-graph/src/main/groovy/carnival/graph/WithPropertyDefsTrait.groovy
@@ -32,7 +32,7 @@ trait WithPropertyDefsTrait {
     // FIELDS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** The set of property definitions */
     Set<PropertyDefinition> propertyDefs = new LinkedHashSet<PropertyDefinition>()
 
 
@@ -41,7 +41,12 @@ trait WithPropertyDefsTrait {
     // BUILDER METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Add the provided property definition to the set of stored property 
+     * definitions.
+     * @param propertyDef The property definition to store
+     * @return This object
+     */
     public WithPropertyDefsTrait withPropertyDef(PropertyDefinition propertyDef) {
         propertyDefs.add(propertyDef)
         return this
@@ -54,25 +59,41 @@ trait WithPropertyDefsTrait {
     // PROPERTY METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Get the labels of the properties that should have unique values across
+     * instantiated graph elements.
+     * @return The set of string labels
+     */
     public Set<String> getUniquePropertyLabels() {
         return uniqueProperties*.label
     }
 
 
-    /** */
+    /** 
+     * Get the labels of the properties that should be required across 
+     * instantiated graph elements.
+     * @return The set of string labels
+     */
     public Set<String> getRequiredPropertyLabels() {
         return requiredProperties*.label
     }
 
 
-    /** */
+    /** 
+     * Get the labels of the properties that should be indexes in the graph
+     * database engine.
+     * @return The set of string labels
+     */
     public Set<String> getIndexedPropertyLabels() {
         return indexedProperties*.label
     }
 
 
-    /** */
+    /** 
+     * Get the set of property definitions whose values should be unique
+     * across the instantiated elements.
+     * @return The set of property deinitions
+     */
     public Set<PropertyDefinition> getUniqueProperties() {
         return propertyDefs.findAll {
             it.unique
@@ -80,7 +101,11 @@ trait WithPropertyDefsTrait {
     }
 
 
-    /** */
+    /** 
+     * Get the set of property definitions that should be required to have 
+     * values in instantiated elements.
+     * @return The set of property definitions
+     */
     public Set<PropertyDefinition> getRequiredProperties() {
         return propertyDefs.findAll {
             it.required
@@ -88,7 +113,11 @@ trait WithPropertyDefsTrait {
     }
 
 
-    /** */
+    /** 
+     * Get the property definitions that should be indexed by the graph 
+     * database engine.
+     * @return The set of property definitions
+     */
     public Set<PropertyDefinition> getIndexedProperties() {
         return propertyDefs.findAll {
             it.index
@@ -96,14 +125,22 @@ trait WithPropertyDefsTrait {
     }
 
 
-    /** */
+    /** 
+     * Get the property definitions that have default values set.
+     * @return The set of property definitions
+     */
     public Set<PropertyDefinition> getDefaultProperties() {
         return propertyDefs.findAll {
             it.defaultValue != null
         }
     }
 
-    /** */
+    /** 
+     * Return the set of properties of the provided element that are defined
+     * by this trait.
+     * @param e The element to test
+     * @return The set of properties.
+     */
     public Set<Property> definedPropertiesOf(Element e) {
         Set<Property> eProps = new HashSet<Property>()
         propertyDefs.each { pDef ->