MUINOR: Docs.

phptek · Jul 1, 2016 · 09c1378 · 09c1378
1 parent dd16546
commit 09c1378
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -26,19 +26,13 @@ or [Postgres' JSON operators](https://www.postgresql.org/docs/9.5/static/functio
 
 ### Why?
 
-I've been wanting to write this module for over two years. Prior-to and during that time I have encountered
-scenarios in more than one project where storing several (10s) of terse configuration parameters in separate database columns
-just seemed crazy. 
+Project scenarios where storing 10s of terse configuration parameters in separate database columns
+just seems crazy. 
 
-There's also the time all you wanted was a simple key -> value store but didn't want to muck
-about with the overhead of two or more datastores like MySQL or Postgres together with MongoDB for example.
+When all you wanted was a simple key / value store but didn't want to muck about with the overhead of two or more
+datastores like an RDBMS together with MongoDB for example.
 
-On one project I went as far as declaring that an entire tab's fields within `getCMSFields()`
-would take their data from, and update-to, a single field comprising JSON data for one aspect of the system's
-configuration.
-
-And if you needed any further convincing that a JSON store in an RDBMS is not such a crazy idea, well Postgres, MySQL, Oracle and MSSQL 2016
-all have, or at time of writing, are planning to have, just such a field.
+That Postgres, MySQL, Oracle and MSSQL 2016 all have, or at time of writing, are planning to have, Database level JSON field-types.
 
 ### Postgres
 

diff --git a/docs/en/configuration.md b/docs/en/configuration.md
@@ -1,13 +1,14 @@
 # Configuration
 
-As the [README](../../README.md) suggests, you can put the module into `postgres` (The default) or `mysql` mode, but only `postgres` works at this time. You can
-do this via standard SS config in your project's `mysite/_config/config.yml` file thus:
+As the [README](../../README.md) suggests you can put the module into `postgres` (The default) or `mysql` mode, but only `postgres` works at this time. You can
+do this via standard SS config in your project's `mysite/_config/config.yml` file:
 
     JSONText:
       backend: postgres
 
 
 Notes: 
 
-* The module uses namespacing so take this into account when calling any part of the module's public API. 
-* The module default is to use `postgres` which is also the only backend that will work at the moment.
+The module uses PSR-1 namespacing, so take this into account when calling any part of the module's public API in your own logic.
+The exception to the rule is that you can still use "JSONText" without the full namespace when declaring your model's `$db` static
+via the built-in magic of `Injector`.
diff --git a/docs/en/usage.md b/docs/en/usage.md
@@ -1,11 +1,10 @@
 # Usage
 
-In the examples below, if you pass invalid queries, expressions or malformed JSON (where applicable) an instance of `JSONTextException` is thrown.
+In the examples below, when passed invalid queries, expressions or malformed JSON (where applicable), then an instance of `JSONTextException` is thrown.
 
 ## General
 
-You can stipulate what format you want your query results back in, by passing one of 
-**json**, **array** or **silverstripe** to the `setReturnType()` method, thus:
+You can stipulate the format you want your query results back as by passing: **json**, **array** or **silverstripe** to the `setReturnType()` method:
 
 **JSON**
 ```
@@ -29,8 +28,7 @@ You can stipulate what format you want your query results back in, by passing on
     $field->setReturnType('silverstripe');
 ```
 
-The module's overloaded declaration of the standard SS `setValue()` method is also chainable for a slightly
-cleaner syntax:
+The module's overloaded `setValue()` method is also chainable for a slightly cleaner syntax:
 
 **Chaining**
 ```
@@ -47,6 +45,9 @@ A small handful of simple query methods `first()`, `last()` and `nth()` exist fo
     class MyDataObject extends DataObject
     {
     
+        /**
+         * @var array
+         */
         private static $db = [
             'MyJSON'    => 'JSONText'
         ];
@@ -85,6 +86,10 @@ You can also use Postgres-like JSON querying syntax, for querying more complex J
 ```
     class MyOtherDataObject extends DataObject
     {
+    
+        /**
+         * @var array
+         */
         private static $db = [
             'MyJSON'    => 'JSONText'
         ];
@@ -143,6 +148,9 @@ See: [Table of JSONPath expressions](jsonpath.md)
                                     ]
                                 }';
     
+        /**
+         * @var array
+         */
         private static $db = [
             'MyJSON'    => 'JSONText'
         ];
@@ -203,40 +211,54 @@ node will be modified with the data passed to `setValue()` as the standard `$val
 ```
     class MyDataObject extends DataObject
     {
-            /*
-             * @var string
-             */
-             protected $stubJSON = '{ "store": {
-                                        "book": [ 
-                                          { "category": "reference",
-                                            "author": "Nigel Rees",
-                                          },
-                                          { "category": "fiction",
-                                            "author": "Evelyn Waugh",
-                                          }
-                                        ]
-                                    }';
+        /*
+         * @var string
+         */
+         protected $stubJSON = '{ "store": {
+                                    "book": [ 
+                                      { "category": "reference",
+                                        "author": "Nigel Rees",
+                                      },
+                                      { "category": "fiction",
+                                        "author": "Evelyn Waugh",
+                                      }
+                                    ]
+                                }';
         
-            private static $db = [
-                'MyJSON'    => 'JSONText'
-            ];
+        /**
+         * @var array
+         */
+        private static $db = [
+            'MyJSON'    => 'JSONText'
+        ];
+        
+        public function requireDefaultRecords()
+        {
+            parent::requireDefaultRecords();
+        
+            if (!$this->MyJSON) {
+                $this->setField($this->MyJSON, $this->stubJSON);
+            }
+        }
             
-            public function requireDefaultRecords()
-            {
-                parent::requireDefaultRecords();
-                
-                if (!$this->MyJSON) {
-                    $this->setField($this->MyJSON, $this->stubJSON);
-                }
+        /**
+         * @param array $update
+         * @return mixed void | null
+         */
+        public function updateMyStuff(array $update = [])
+        {
+            if (empty($update)) {
+                return;
             }
-    
+            
             // Perform a multiple node update
             $newReference = [
-                'category'  => "new-age",
-                'author'    => "Lucy Lastic"
+                'category'  => $update[0],
+                'author'    => $update[1]
             ];
-    
+
             $field->setValue($newReference, null, '$.store.book.[0]');
+        }
     
     }
 ```