#113

app/carnival-core/src/main/groovy/carnival/core/Core.groovy

@@ -16,7 +16,11 @@ import carnival.graph.VertexModel
 
 
 /** 
- * The Core graph model.
+ * The Core graph model.  The intention is for this model to be linked to
+ * published ontologies such that there is congruency between the terms and
+ * relations of this model and those of the published ontologies.  Future 
+ * versions of Carnival will explicitly include this linkage.  The current
+ * model is minimally documented in anticipation of this enhancement.
  *
  */
 class Core {

app/carnival-gradle/src/main/groovy/carnival/gradle/CarnivalLibraryPlugin.groovy

@@ -12,6 +12,9 @@ import org.gradle.api.Project
  */
 class CarnivalLibraryPlugin implements Plugin<Project> {
 
+    /**
+     * Apply a consistent set of Carnival dependencies to the Gradle project.
+     */
     void apply(Project project) {
         // dependency versions
         Locale locale = new Locale("en", "US");

app/carnival-graph/src/main/groovy/carnival/graph/Definition.groovy

@@ -17,11 +17,19 @@ import carnival.util.StringUtils
 import carnival.graph.Base
 
 
-
+/**
+ * A collection of static methods relevent to element definitions.
+ */
 @Slf4j
 class Definition {
 
-    /** */
+    /** 
+     * Look up the element definition of the provided element.  If the element
+     * is a vertex, a VertexDefinition will be returned; if the element is an
+     * edge, and EdgeDefinition will be returned.
+     * @param v The source element
+     * @return The ElementDefinition that applies to the element.
+     */
     static public ElementDefinition lookupElementDefinition(Element v) {
         assert v != null
         assert (v instanceof Edge || v instanceof Vertex)
@@ -61,14 +69,24 @@ class Definition {
     }
 
 
-    /** */
+    /** 
+     * Look up the vertex definition of the provided vertex.
+     * @param v The source vertex
+     * @return The VertexDefinition that applies to the vertex
+     * @see #lookupElementDefinition(Element)
+     */
     static public VertexDefinition lookup(Vertex v) {
         assert v != null
         lookupElementDefinition(v)
     }    
 
 
-    /** */
+    /** 
+     * Look up the edge definition of the provided edge.
+     * @param v The source edge
+     * @return The EdgeDefinition that applies to the edge
+     * @see #lookupElementDefinition(Element)
+     */
     static public EdgeDefinition lookup(Edge e) {
         assert e != null
         lookupElementDefinition(e)

app/carnival-graph/src/main/groovy/carnival/graph/DynamicVertexDef.groovy

@@ -19,50 +19,42 @@ import carnival.util.StringUtils
 
 
 
-/** */
+/** 
+ * DynamicVertexDef is a VertexDefinition that is created in code outside the
+ * normal model definition construction of enumerated classes tagged with 
+ * @VertexModel.
+ */
 @ToString
 @EqualsAndHashCode(allProperties=true)
 class DynamicVertexDef implements VertexDefinition {
 
-    /** 
-     * @param name The name of the vertex def formatted as per Java enum convention, eg. SOME_NAME
-     *
-     */
-    static public DynamicVertexDef singletonFromScreamingSnakeCase(Graph graph, GraphTraversalSource g, String name) {
-        def dvf = new DynamicVertexDef(name)
-        if (dvf.isClass()) dvf.vertex = dvf.instance().vertex(graph, g)
-        return dvf
-    }
-
-    /** 
-     * @param name The name of the vertex def formatted in camel case, eg. SomeName
-     *
-     */
-    static public DynamicVertexDef singletonFromCamelCase(Graph graph, GraphTraversalSource g, String name) {
-        singletonFromScreamingSnakeCase(
-            graph, 
-            g, 
-            StringUtils.toScreamingSnakeCase(name)
-        )
-    }
-
-    /** */
+    /** The name of the vertex definition */
     String name
 
-    /** */
+    /** Override the namespace calculated from the classpath */
     String nameSpaceOverride
 
-    /** */
+    /** 
+     * Private constructor.
+     * @param name The name of the vertex definition.
+     */
     private DynamicVertexDef(String name) {
         this.name = name
     }
 
-    /** */
+    /** 
+     * Returns the name of the vertex definition.
+     * @return The name of this vertex definition
+     */
     public String name() {
         return this.name
     }
 
-    /** */
+    /** 
+     * Returns the namespace of this vertex definition, which will be
+     * calculated from the class if not overridden.
+     * @return The name space of this vertex definition
+     */
     @Override
     public String getNameSpace() {
         if (this.nameSpaceOverride != null) return this.nameSpaceOverride
@@ -76,7 +68,11 @@ class DynamicVertexDef implements VertexDefinition {
         return "${this.metaClass.theClass.name}"
     }
 
-    /** */
+    /** 
+     * Set the name space of this definition to the provided value, which will
+     * be used in getNameSpace() rather than the calculated value.
+     * @param ns The namespace to use for this definition
+     */
     public void setNameSpace(String ns) {
         this.nameSpaceOverride = ns
     }

app/carnival-graph/src/main/groovy/carnival/graph/EdgeBuilder.groovy

@@ -25,22 +25,25 @@ class EdgeBuilder extends PropertyValuesHolder<EdgeBuilder> {
     ///////////////////////////////////////////////////////////////////////////
 
     /** 
-     * Object that owns this builder.
-     * */
+     * The edge definition that will be used to create edges.
+     */
     EdgeDefinition edgeDef
 
-    /** */
+    /** The from or out vertex for created edges */
     Vertex fromVertex
 
-    /** */
+    /** The to or in vertex for created edges */
     Vertex toVertex
 
 
     ///////////////////////////////////////////////////////////////////////////
     // CONSTRUCTOR
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Constructor that takes the edge definition as an argument.
+     * @param edgeDef The edge definition this builder will use.
+     */
     public EdgeBuilder(EdgeDefinition edgeDef) {
         assert edgeDef
         this.edgeDef = edgeDef
@@ -51,22 +54,31 @@ class EdgeBuilder extends PropertyValuesHolder<EdgeBuilder> {
     // GETTERS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Return the element element definition of this builder.
+     * @return The ElementDefinition
+     */
     public ElementDefinition getElementDef() { edgeDef }
 
 
     ///////////////////////////////////////////////////////////////////////////
     // UTILITY METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Convenience string representation of this object.
+     * @return A string representation of this object
+     */
     public String toString() {
         def str = "${edgeDef}"
         if (propertyValues.size() > 0) str += " ${propertyValues}"
         return str
     }
 
-    /** */
+    /** 
+     * Assert that the properties required by the edge definition have been
+     * set.
+     */
     void assertRequiredProperties() {
         edgeDef.requiredProperties.each { requiredPropDef ->
             boolean found = allPropertyValues().find { k, v ->
@@ -81,7 +93,11 @@ class EdgeBuilder extends PropertyValuesHolder<EdgeBuilder> {
     // BUILDER METHODS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Sets the from vertex for created edges.
+     * @param v The from vertex
+     * @return This object
+     */
     public EdgeBuilder from(Vertex v) {
         assert v != null
         edgeDef.assertDomain(v)
@@ -90,7 +106,11 @@ class EdgeBuilder extends PropertyValuesHolder<EdgeBuilder> {
     }
 
 
-    /** */
+    /** 
+     * Sets the to vertex for created edges.
+     * @param v The to vertex
+     * @return This object
+     */
     public EdgeBuilder to(Vertex v) {
         edgeDef.assertRange(v)
         toVertex = v