#113

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

@@ -10,6 +10,9 @@ import groovy.transform.ToString
 import groovy.transform.InheritConstructors
 import groovy.util.logging.Slf4j
 
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+
 import org.apache.commons.configuration.PropertiesConfiguration
 
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal
@@ -30,7 +33,9 @@ import carnival.core.graph.DefaultGraphValidator
 
 
 
-/** */
+/** 
+ * A Carnival implementation with an underlying Neo4j graph.
+ */
 @InheritConstructors
 @Slf4j
 class CarnivalNeo4j extends Carnival {
@@ -39,7 +44,13 @@ class CarnivalNeo4j extends Carnival {
 	// STATIC
 	///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** A log used to log Cypher statements */
+    static Logger sqllog = LoggerFactory.getLogger('sql')
+
+
+    /** 
+	 * Create a CarnivalNeo4j object.
+	 */
     public static CarnivalNeo4j create(Map args = [:]) {
 		CarnivalNeo4jConfiguration defaultConfig = CarnivalNeo4jConfiguration.defaultConfiguration()
 		create(defaultConfig, args)
@@ -361,5 +372,27 @@ class CarnivalNeo4j extends Carnival {
 		    echo("done")
 		}
 	}
+
+	///////////////////////////////////////////////////////////////////////////
+	// CYPHER
+	///////////////////////////////////////////////////////////////////////////
+
+    /** */
+    public Object cypher(String q) {
+        sqllog.info("CarnivalNeo4j.cypher:\n$q")
+        assert graph
+        return graph.cypher(q)
+    }
+
+
+    /** */
+    public Object cypher(String q, Map args) {
+        sqllog.info("CarnivalNeo4j.cypher:\n$q\n$args")
+        assert graph
+        return graph.cypher(q, args)
+    }
+
+
+
 
 }

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

@@ -14,6 +14,9 @@ import carnival.graph.VertexBuilder
 
 
 
+/**
+ * A configuration object for a CarnivalNeo4j.
+ */
 @Slf4j
 @ToString(includeNames=true)
 class CarnivalNeo4jConfiguration {
@@ -22,8 +25,13 @@ class CarnivalNeo4jConfiguration {
     // STATIC
     ///////////////////////////////////////////////////////////////////////////
 
+    /** The default relative file path for the neo4j graph */
     final static String GRAPH_PATH_DEFAULT = "carnival-home/neo4j/graph"
 
+    /** 
+     * Returns a default configuration object.
+     * @return A default CarnivalNeo4j configuration.
+     */
     static public CarnivalNeo4jConfiguration defaultConfiguration() {
         Path currentRelativePath = Paths.get("")
         Path carnivalHomePath = currentRelativePath.resolve(GRAPH_PATH_DEFAULT)
@@ -39,12 +47,25 @@ class CarnivalNeo4jConfiguration {
     ///////////////////////////////////////////////////////////////////////////
     // CONFIG FIELDS
     ///////////////////////////////////////////////////////////////////////////
+
+    /**
+     * A data holder for CarnivalNeo4j configuration elements.  See the Neo4j
+     * documentation for a description of each configuration element.
+     */
     @ToString(includeNames=true)
     static class Gremlin {
 
         @ToString(includeNames=true)
         static class Neo4j {
+
+            /** The directory Neo4j will use for the database files */
             String directory
+
+            /** 
+             * If true, an empty database directory will be created if it does
+             * not already exist; Neo4j requires that the directy be present
+             * when the database starts up. 
+             */
             Boolean directoryCreateIfNotPresent = true
 
             @ToString(includeNames=true)
@@ -87,8 +108,4 @@ class CarnivalNeo4jConfiguration {
     Gremlin gremlin = new Gremlin()
 
 
-
-
-
-
 }

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

@@ -24,7 +24,9 @@ import carnival.core.graph.DefaultGraphValidator
 
 
 
-/** */
+/** 
+ * A Carnival with an underlying Tinkergraph implementation.
+ */
 @InheritConstructors
 @Slf4j
 class CarnivalTinker extends Carnival {
@@ -33,7 +35,10 @@ class CarnivalTinker extends Carnival {
 	// FACTORY 
 	///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Create a ready-to-use CarnivalTinker object.
+     * @return A CarnivalTinker object.
+     */
     public static CarnivalTinker create(Map args = [:]) {
 		log.info "CarnivalTinker create args:$args"
 
@@ -65,7 +70,9 @@ class CarnivalTinker extends Carnival {
     // LIFE-CYCLE
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Close this Carnival.
+     */
     public void close() {
         graph.close()
     }

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

@@ -34,7 +34,7 @@ class Core {
 	// in this file.
 	///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** Core vertex model. */
     @VertexModel
     static enum VX {
         APPLICATION (
@@ -101,7 +101,7 @@ class Core {
     }
 
 
-    /** */
+    /** Core edge model */
     @EdgeModel
     static enum EX {
     	IS_IDENTIFIED_BY,
@@ -140,7 +140,7 @@ class Core {
     }
 
 
-    /** */
+    /** Core property model */
     @PropertyModel
     static enum PX {
         NAME,