Merge pull request #162 from robertoschwald/3.x_docs

#161 Extended plugin docs

plugin/src/docs/implementation.adoc

@@ -1,4 +1,5 @@
 == Implementation
+Most of the plugin code is marked as @CompileStatic.
 
 === AuditLogEventListener
 The Audit Logging plugin registers a PersistenceEventListener (`AuditLogListener`) bean per datasource, which listens to GORM events.
@@ -11,3 +12,11 @@ The Plugin Descriptor (AuditLogListenerGrailsPlugin) configures the plugin durin
 
  * Configures the plugin either by default values - see DefaultAuditLogConfig.groovy - or by user configured settings.
  * Registers a PersistenceEventListener bean per datasource
+
+=== Auditable trait
+Enabling auditing on a Domain class is done by implementing the `Auditable` trait.
+
+=== Stampable trait
+Enabling stamping on a Domain class is done by implementing the `Stampable` trait.
+This trait adds the properties dateCreated, lastUpdated, createdBy, lastUpdatedBy
+to the domain class.

plugin/src/docs/installation.adoc

@@ -31,4 +31,33 @@ This will create the Audit Domain class as well as configure:
 
 Once created, you should open the generated file to adjust the `mappings` and `constraints` to suit your needs.
 
-WARNING: Be sure to respect the existing nullability constraints or the plugin may not work correctly
+WARNING: Be sure to respect the existing nullability constraints or the plugin may not work correctly
+
+=== Prepare your Domain classes for Auditing
+
+For every Domain class you want to be audited, implement the Auditable Trait.
+
+For example:
+
+```groovy
+
+import grails.plugins.orm.auditable.Auditable
+
+class MyDomain implements Auditable {
+    String whatever
+    ...
+}
+```
+
+
+If you additionally want to enable stamping, implement the Stampable Trait:
+
+```groovy
+
+import grails.plugins.orm.auditable.Auditable
+
+ class MyDomain implements Auditable, Stampable {
+     String whatever
+     ...
+ }
+ ```

plugin/src/docs/stamping.adoc

@@ -17,7 +17,8 @@ The attributes will assume the default constraints, which should be fine for mos
 You can configure the `constraints` and `mappings` block as usual in your domain class to customize the stampable properties.
 
 === Stamping Configuration
-Previous versions used an AST transformation to apply the stamping and could allow more configuration. For now, the stamping support has been boiled down to just the basic trait attributes and the ability to disable the plugin globally.
+Previous versions used an AST transformation to apply the stamping and could allow more configuration.
+For now, the stamping support has been boiled down to just the basic trait attributes and the ability to disable the plugin globally.
 
 [source,groovy]
 ----
@@ -26,3 +27,21 @@ grails.plugin.auditLog.stampEnabled = true
 ----
 
 WARNING: If you disable stamping but have `Stampable` entities, they will likely fail validation since the plugin will not be populating the fields which are still added to the domain objects. The main reason to disable stamping is to prevent the listener registration in the case that you just aren't using the `Stampable` support.
+
+If you want to mark *all* of your domain objects as stampable, you could define the following `TraitInjector`:
+
+[source,groovy]
+----
+@CompileStatic
+class StampableTraitInjector implements TraitInjector {
+    @Override
+    Class getTrait() {
+        Stampable
+    }
+
+    @Override
+    String[] getArtefactTypes() {
+        ['Domain'] as String[]
+    }
+}
+----

plugin/src/docs/upgrading.adoc

@@ -1,5 +1,7 @@
 == Upgrading
 
+The 3.0.0 version of the plugin is a major rewrite of the codebase. Therefore you need to upgrade your code for this version.
+
 === Domain Classes
 Prior versions of the plugin used a static property syntax to enable and customize logging:
 [source,groovy]
@@ -11,10 +13,18 @@ static auditable = true
 static auditable = [auditableProperties: ['name', 'famous', 'lastUpdated']]
 ----
 
-Starting with version 3.0.0, the plugin uses an `Auditable` trait as both a marker as well as a way to configure and override auditing behavior.
+Starting with version 3.0.0, the plugin uses an `Auditable` trait and/or a `Stampable` trait as both a marker as well as a way to configure and override auditing behavior.
 
 For the first example, just adding `implements Auditable` will enable the default behavior.
 
+[source,groovy]
+----
+import grails.plugins.orm.auditable.Auditable
+class MyDomain implements Auditable {
+  ..
+}
+----
+
 For the second example above, you simply override the appropriate method on the `Auditable` trait, in this case the method is `getLogIncluded()`:
 
 [source,groovy]