Merge pull request #21 from matrei/matrei/update-documation

Documentation updates

build.gradle

@@ -114,6 +114,8 @@ allprojects { project ->
                 'version': project.version,
                 'imagesdir': 'images',
                 'sourcedir': "${project.projectDir}/src/main/groovy"
+
+        baseDirFollowsSourceFile()
     }
 
     task copyDocs(type: Copy, dependsOn: asciidoctor) {

developer/src/docs/asciidoc/gettingStarted.adoc

@@ -2,70 +2,46 @@
 === Checking out and Building 
 
 
-The project is currently hosted on Github at [https://github.com/grails/grails-data-mapping].
+The project is https://github.com/grails/grails-data-mapping[hosted on GitHub].
 
 You are free to fork the project from there or clone it anonymously using git:
 
-[source,groovy]
 ----
-git clone git@github.com:grails/grails-data-mapping.git
+git clone https://github.com/grails/grails-data-mapping.git
 cd grails-data-mapping
 ----
 
-The project has a https://gradle.org[Gradle] build. You will need Intellij 15 or greater to work with the source code.
-
-Use the Intellij 15 Gradle tooling to import the project.
-
+The project has a https://gradle.org[Gradle] build.
 
 To build the project you can run the `assemble` task:
 
-[source,groovy]
 ----
 ./gradlew assemble
 ----
 
 To install the jar files for the various subprojects into your local Maven repository you can run:
 
-[source,groovy]
 ----
-./gradlew install
+./gradlew publishToMavenLocal
 ----
 
-To build all of the documentation run the command:
-
-[source,groovy]
-----
-./gradlew allDocs
-----
-
-Documentation will produced in the `build/docs` directory.
-
-NOTE: If you experience PermGen errors when building documentation you may need to increase the JVM permgen inside GRADLE_OPTS
-
-
 === Project Structure
 
-
 The project is essentially a multi-project Gradle build. There is a core API and then subprojects that implement that API. The core API subprojects include:
 
 * `grails-datastore-core` - The core API, this provides core interfaces for implementing a GORM provider
-* `grails-datastore-gorm` - The runtime meta-programming and AST transformation infrastructure behind GORM. Also provides end users APIs like `grails.gorm.CriteriaBuilder` and `grails.gorm.DetachedCriteria` 
+* `grails-datastore-gorm` - The runtime meta-programming and AST transformation infrastructure behind GORM. This also provides end users with APIs like `grails.gorm.CriteriaBuilder` and `grails.gorm.DetachedCriteria`
 * `grails-datastore-gorm-support` - Support classes for easing the writing of a GORM plugin for Grails
 * `grails-datastore-gorm-tck` - The TCK that includes hundreds of Spock specifications that a GORM implementation will need to pass
 * `grails-datastore-web` - Classes required to integrate GORM into a web tier
 
-Beyond these core subprojects there are implementations for various datastores. For example:
-
-* `grails-datastore-mongodb/grails-datastore-gorm-hibernate` - GORM for Hibernate
-* `grails-datastore-mongodb/grails-datastore-gorm-mongo` - GORM for MongoDB project [https://grails.org/plugin/mongodb]
-* `grails-datastore-neo4j` - GORM for Neo4j project [https://grails.org/plugin/neo4j]
-* `grails-datastore-redis/grails-datastore-gorm-redis` - GORM for Redis project [https://grails.org/plugin/redis]
-* `grails-datastore-cassandra/grails-datastore-gorm-cassandra` - GORM for Cassandra project [https://grails.org/plugin/cassandra]
-
-
-The documentation for each implementation is kept in the documentation subprojects that start with `grails-documentation`. There are documentation projects for the core API, MongoDB, Neo4j, Redis, and Cassandra.
-
-Finally the Grails 3 plugins that are used to distribute the GORM implementations to end users can be found in the `grails-plugins` directory and the `grails2-plugins` directory for Grails 2.x.
+In addition to this, there are separate projects of GORM implementations for various datastores:
 
+* https://github.com/grails/gorm-hibernate4[GORM for Hibernate 4]
+* https://github.com/grails/gorm-hibernate5[GORM for Hibernate 5]
+* https://github.com/grails/gorm-mongodb[GORM for MongoDB]
+* https://github.com/grails/gorm-neo4j[GORM for Neo4j]
+* https://github.com/grails/gorm-redis[GORM for Redis]
+* https://github.com/grails/gorm-cassandra[GORM for Cassandra]
 
 

developer/src/docs/asciidoc/index.adoc

@@ -1,9 +1,13 @@
-= GORM Developer Guide
-Graeme Rocher
 :imagesdir: ./images
 :source-highlighter: coderay
+:toc: left
+:toc-title: GORM Developer Guide
+:numbered:
 :last-update-label!:
 
+= GORM Developer Guide
+Graeme Rocher
+
 [[introduction]]
 == Introduction
 
@@ -55,6 +59,6 @@ include::understandingApi/gormApis.adoc[]
 include::testing.adoc[]
 
 [[stepByStep]]
-== Step by Step Guide to Creating an Implementation
+== Step-by-Step Guide to Creating an Implementation
 
 include::stepByStep.adoc[]

developer/src/docs/asciidoc/introduction.adoc

@@ -1,8 +1,8 @@
-This documentation describes the GORM API mechanics and how a datastore implementation can be built to interface to any database providing a GORM API onto it. This documentation is mainly targeted at developers interested in creating implementations of GORM ontop of alternative datastores.
+This documentation describes the GORM API mechanics and how a datastore implementation can be built to interface to any database providing a GORM API onto it. This documentation is mainly targeted at developers interested in creating implementations of GORM on top of alternative datastores.
 
 As of this writing the project has several implementations of GORM against a variety of different datastore implementations. Current implementations include:
 
-* Hibernate 3,4 and 5
+* Hibernate 3, 4 and 5
 * MongoDB
 * Redis
 * Neo4j

developer/src/docs/asciidoc/stepByStep.adoc

@@ -1,14 +1,13 @@
-To get started with your a new GORM implementation the following steps are required:
+To get started with a new GORM implementation, the following steps are required:
 
 
 === Initial Directory Creation
 
 
-[source,groovy]
 ----
-$ git clone git@github.com:grails/grails-data-mapping.git
-$ cd grails-data-mapping
-$ mkdir grails-datastore-gorm-xyz
+git clone https://github.com/grails/grails-data-mapping.git
+cd grails-data-mapping
+mkdir grails-datastore-gorm-xyz
 ----
 
 
@@ -17,31 +16,29 @@ $ mkdir grails-datastore-gorm-xyz
 
 Create build.gradle:
 
-[source,groovy]
 ----
-$ vi grails-datastore-gorm-xyz/build.gradle
+vi grails-datastore-gorm-xyz/build.gradle
 ----
 
 With contents:
 
 [source,groovy]
 ----
 dependencies {
-    compile project(':grails-datastore-gorm'),
+    implementation project(':grails-datastore-gorm'),
             project(':grails-datastore-web'),
             project(':grails-datastore-gorm-support')
             
-    testCompile project(':grails-datastore-gorm-tck')
+    testImplementation project(':grails-datastore-gorm-tck')
     testRuntime "javax.servlet:javax.servlet-api:$servletApiVersion"
 
 }
 ----
 
 Add new project to settings.gradle in root project:
 
-[source,groovy]
 ----
-$ vi settings.gradle
+vi settings.gradle
 ----
 
 Changes shown below:
@@ -51,33 +48,30 @@ Changes shown below:
 // GORM Implementations
 'grails-datastore-gorm-neo4j',
 'grails-datastore-gorm-xyz',
-....
+...
 ----
 
 
 === Create Project Source Directories
 
 
-[source,groovy]
 ----
-$ mkdir grails-datastore-gorm-xyz/src/main/groovy
-$ mkdir grails-datastore-gorm-xyz/src/test/groovy
+mkdir grails-datastore-gorm-xyz/src/main/groovy
+mkdir grails-datastore-gorm-xyz/src/test/groovy
 ----
 
 
-=== Generate IDE Project Files and Import into IDE
+=== Generate IDE Project Files and Import into IDE (Optional)
 
 
-[source,groovy]
 ----
-$ gradlew grails-datastore-gorm-xyz:idea
+./gradlew grails-datastore-gorm-xyz:idea
 ----
 
 Or
 
-[source,groovy]
 ----
-$ gradlew grails-datastore-gorm-xyz:eclipse
+./gradlew grails-datastore-gorm-xyz:eclipse
 ----
 
 

developer/src/docs/asciidoc/testing.adoc

@@ -1,4 +1,4 @@
-The `grails-datastore-gorm-tck` project provides a few hundred tests that ensure a particular GORM implementation is compliant. To use the TCK you need to define a dependency on the TCK in the subprojects `build.gradle` file:
+The `grails-datastore-gorm-tck` project provides several hundred tests to guarantee that a particular GORM implementation is compliant. To use the TCK you need to define a dependency on the TCK in the subprojects `build.gradle` file:
 
 [source,groovy]
 ----
@@ -41,11 +41,11 @@ class Setup {
 }
 ----
 
-Some setup code has been omitted for clarity but basically the `Setup.groovy` class should initiase the `Datastore` and return a `Session` from the static `setup` method which gets passed a list of classes that need to be configured.
+Some setup code has been omitted for clarity, but essentially, the `Setup.groovy` class should initialize the `Datastore` and return a `Session` from the static setup method, which is passed a list of classes to configure.
 
-With this done all of the TCK tests will run against the subproject. If a particular test cannot be implemented because the underlying datastore doesn't support the feature then you can create a test that matches the name of the test that is failing and it will override said test.
+With this setup, all the TCK tests will be run against the subproject. If a specific test cannot be implemented due to the underlying datastore lacking support for a particular feature, you can create a test with the same name as the failing test, and that will then override the corresponding test in the TCK.
 
-For example SimpleDB doesn't support pagination so there is a `grails.gorm.tests.PagedResultSpec` class that overrides the one from the TCK. Each test is a Spock specification and Spock has an `Ignore` annotation that can be used to ignore a particular test:
+For example: SimpleDB doesn't support pagination. Add a `grails.gorm.tests.PagedResultSpec` class that overrides the one from the TCK. Each test is a Spock specification and Spock has an `Ignore` annotation that can be used to ignore a particular test:
 
 [source,groovy]
 ----

developer/src/docs/asciidoc/understandingApi.adoc

@@ -1,9 +1,7 @@
 
 === Introduction
 
+The GORM Developer API is divided into a low-level API that implementors must implement for each specific datastore, and a set of higher-level APIs that enhance domain classes with features visible to regular users, such as dynamic finders, criteria queries, and so on.
 
-The GORM Developer API is split into a low-level API that implementors need to implement for each individual datastore and then set of higher level APIs that enhance domain classes with things regular users see such as dynamic finders, criteria queries and so on.
-
-The low-level API classes are found in the `grails-datastore-core` subproject, whilst the higher level APIs used to enhance domain classes are found in `grails-datastore-gorm`. In this section we will discuss the low-level API.
-
+The low-level API classes are located within the `grails-datastore-core` subproject, whereas the higher-level APIs used to enhance domain classes can be found in `grails-datastore-gorm`. In this section, we will discuss the low-level API.
 

developer/src/docs/asciidoc/understandingApi/datastoreBasics.adoc

@@ -1,5 +1,5 @@
 
-=== The MappingContext
+==== The MappingContext
 
 
 The `org.grails.datastore.mapping.model.MappingContext` interface is used to obtain metadata about the classes that are configured for persistence. There are `org.grails.datastore.mapping.model.PersistentEntity` and `org.grails.datastore.mapping.model.PersistentProperty` interfaces that represent a class and its properties respectively. These can be obtained and introspected via the `MappingContext`.
@@ -49,12 +49,12 @@ class Neo4jMappingContext extends AbstractMappingContext {
 Notice how Neo4j provides a custom `GraphGormMappingFactory` and `GraphPersistentEntity` to allow the domain class configuration to be changed for a given Neo4j `Node`.
 
 
-=== The Datastore Interface
+==== The Datastore Interface
 
 
 The `org.grails.datastore.mapping.core.Datastore` interface is the equivalent of a SQL `DataSource` where by it provides the necessary capability to create a connection. In most cases one can simply subclass the `AbstractDatastore` super class and implement the `createSession` method. The following implementation is from the `SimpleMapDatastore` which implements GORM ontop of a `ConcurrentHashMap`:
 
-[source,groovy]
+[,java]
 ----
 @Override
 protected Session createSession(PropertyResolver connDetails) {
@@ -64,7 +64,7 @@ protected Session createSession(PropertyResolver connDetails) {
 
 The implementation depends a lot on the underlying datastore. For example for MongoDB the following implementation is used:
 
-[source,groovy]
+[,java]
 ----
 @Override
 protected Session createSession(PropertyResolver connDetails) {
@@ -76,16 +76,16 @@ Notice that the `Datastore` also has a reference to the `MappingContext` discuss
 
 
 
-=== The Session Interface
+==== The Session Interface
 
 
 The `org.grails.datastore.mapping.core.Session` interface represents an active connection. It can be either stateful or stateless, depending on the implementation. For example of embedded databases where there is no network connection, a stateful session is not particularly useful, but a datastore that creates network connections you may want to cache returned instances to reduce load.
 
 The `AbstractSession` class provides some support for creating stateful sessions, if you prefer a stateless implementation then simply implement `Session` or subclass `AbstractAttributeStoringSession`.
 
-In general if you subclass `AbstractSession` the minimum you need to do is implement the `createPersister` method:
+In general, if you subclass `AbstractSession`, the minimum you need to do is implement the `createPersister` method:
 
-[source,groovy]
+[,java]
 ----
 protected Persister createPersister(Class cls, MappingContext mappingContext) {
     PersistentEntity entity = mappingContext.getPersistentEntity(cls.getName());
@@ -97,4 +97,4 @@ protected Persister createPersister(Class cls, MappingContext mappingContext) {
 }
 ----
 
-The example above is from the `SimpleMapSession` implementation, which creates a `SimpleMapEntityPersister` instance and returns it. Returning null indicates that the class cannot be persisted and an exception will be thrown
+The example above is from the `SimpleMapSession` implementation, which creates a `SimpleMapEntityPersister` instance and returns it. Returning null indicates that the class cannot be persisted and an exception will be thrown.

developer/src/docs/asciidoc/understandingApi/gormApis.adoc

@@ -1,4 +1,4 @@
-By default the GORM compiler will make all GORM entities implement the `GormEntity` trait. Which provide all of the default GORM methods. However if you want to extend GORM to provide more methods specific to a given data store you can do so by extending this trait.
+By default, the GORM compiler ensures that all GORM entities implement the `GormEntity` trait, which provides them with all the default GORM methods. Nevertheless, if there's a need to extend GORM functionality to incorporate additional methods tailored to a specific datastore, you can achieve this by extending the `GormEntity` trait.
 
 For example Neo4j adds methods for Cypher querying:
 
@@ -14,7 +14,7 @@ trait Neo4jEntity<D> extends GormEntity<D> {
 }
 ----
 
-With this addition then you then need to tell the GORM compiler to make entities implement this trait. To do that implement a `TraitProvider`:
+With this addition, you need to instruct the GORM compiler to make entities implement this trait. To achieve this, implement a `TraitProvider`:
 
 [source,groovy]
 ----
@@ -32,14 +32,13 @@ class Neo4jEntityTraitProvider implements GormEntityTraitProvider {
 
 And then add a `src/main/resources/META-INF/services/org.grails.compiler.gorm.GormEntityTraitProvider` file specifying the name of your trait provider:
 
-[source,groovy]
 ----
 org.grails.datastore.gorm.neo4j.Neo4jEntityTraitProvider
 ----
 
-GORM will automatically inject to trait into any domain class found in `grails-app/domain` or annotated with the `Entity` annotation, unless Hibernate is on the classpath in which case you have to tell GORM to map the domain class with Neo4j:
+GORM will automatically inject the trait into any domain class discovered in `grails-app/domain` or annotated with the `Entity` annotation. However, if Hibernate is present on the classpath, you must inform GORM to map the domain class with Neo4j:
 
-[source,groovy]
+[,groovy]
 ----
 static mapWith = "neo4j"
 ----

developer/src/docs/asciidoc/understandingApi/gormEnhancer.adoc

@@ -31,7 +31,7 @@ enhancer.enhance()
 def books = Book.list()
 ----
 
-They key part to enabling the usage of all the GORM methods (`list()`, dynamic finders etc.) is the usage of the `MongoGormEnhancer`. This class subclasses `org.grails.datastore.gorm.GormEnhancer` and provides some extensions to GORM specific to MongoDB. A subclass is not required however and if you don't require any datastore specific extensions you can just as easily use the regular `GormEnhancer`:
+The key element for enabling the use of all GORM methods (`list()`, dynamic finders, etc.) is the utilization of the `MongoGormEnhancer`. This class is a subclass of `org.grails.datastore.gorm.GormEnhancer` and offers extensions to GORM specifically tailored for MongoDB. However, a subclass is not mandatory, and if you don't need any datastore-specific extensions, you can equally use the standard `GormEnhancer`:
 
 [source,groovy]
 ----