From 26c8f8b83a2d6fa32741654279dc3141fd447c4e Mon Sep 17 00:00:00 2001
From: Daniel Siepmann <coding@daniel-siepmann.de>
Date: Fri, 12 Aug 2016 17:35:54 +0200
Subject: [PATCH] FEATURE: Improve documentation

* Adjust some php examples
* Adjust example to match both, yaml and php
* Remove wrong example with missing argumentName
---
 Documentation/source/index.rst | 17 +++++++----------
 Documentation/source/usage.rst | 23 +++++++++--------------
 2 files changed, 16 insertions(+), 24 deletions(-)

diff --git a/Documentation/source/index.rst b/Documentation/source/index.rst
index 5f0f566..b3fcf0f 100644
--- a/Documentation/source/index.rst
+++ b/Documentation/source/index.rst
@@ -1,8 +1,6 @@
-.. highlight:: yaml
+.. highlight:: php
 .. DigiComp.SettingValidator documentation master file, created by
    sphinx-quickstart on Fri Jul 15 17:46:40 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 Welcome to DigiComp.SettingValidator's documentation!
 =====================================================
@@ -10,24 +8,23 @@ Welcome to DigiComp.SettingValidator's documentation!
 This Package allows to configure Validators for your Action-Arguments or domain model properties to be set by a new
 Yaml-File in your Configuration directory.
 
-Lets imagine you had this action-method:
-
-.. code-block:: php
+Lets imagine you have this action-method::
 
     /**
      * @param Order $order
      * @Flow\Validate(type="DigiComp.SettingValidator:Settings")
      */
-    public function createOrder($order) {...}
+    public function createOrder(Order $order) {...}
 
-Then your :file:`Validation.yaml` could look like this:
+Then your :file:`Validation.yaml` can look like this:
 
 .. literalinclude:: /examples/Validation.yaml
+   :lines: 1-15
 
 As you see: Nesting is possible ;) That way you can easily construct flexible structures.
 
-The SettingsValidator has an optional option: "name" - If you don't give one, it assumes your validation value is an
-object and searches in Validation.yaml for the FQCN.
+The SettingsValidator has an optional option: ``name`` - If you don't give one, it assumes your validation value is an
+object and searches in :file:`Validation.yaml` for the FQCN.
 
 Contents:
 
diff --git a/Documentation/source/usage.rst b/Documentation/source/usage.rst
index e7599b0..74a065a 100644
--- a/Documentation/source/usage.rst
+++ b/Documentation/source/usage.rst
@@ -1,4 +1,4 @@
-.. highlight:: yaml
+.. highlight:: php
 .. _usage:
 
 Place of configuration
@@ -15,8 +15,7 @@ calling them like :file:`Validation.Users.yaml`.
 Types of configuration
 ======================
 
-Inside this files you define the validation rules either for a fully qualified class name, or a
-custom name.
+You can define the validation rules either for a fully qualified class name, or a custom name.
 
 Given the following :file:`Validation.yaml`:
 
@@ -30,15 +29,13 @@ One class is configured by it's fully qualified class name
 Custom Name
 -----------
 
-If you prefer the name, you have to configure the validator to use the specific name:
-
-.. code-block:: php
+If you prefer the name, you have to configure the validator to use the specific name::
 
     /**
-     * @param Order $order
-     * @Flow\Validate(argumentName="order", type="DigiComp.SettingValidator:Settings", options={"name"="MyCustomName"})
+     * @param OrderCustomer $orderCustomer
+     * @Flow\Validate(argumentName="orderCustomer", type="DigiComp.SettingValidator:Settings", options={"name"="OrderCustomer"})
      */
-    public function createOrder($order) {...}
+    public function createOrder(OrderCustomer $orderCustomer) {...}
 
 .. _types-of-configuration-fqcn:
 
@@ -46,15 +43,13 @@ Fully qualified class namespace
 -------------------------------
 
 If you provide the fully qualified class name, you don't have to provide the additional
-argument, the following code will be enough:
-
-.. code-block:: php
+argument, the following code will be enough::
 
     /**
      * @param Order $order
-     * @Flow\Validate(type="DigiComp.SettingValidator:Settings")
+     * @Flow\Validate(argumentName="order, type="DigiComp.SettingValidator:Settings")
      */
-    public function createOrder($order) {...}
+    public function createOrder(Order $order) {...}
 
 .. _structure-of-configuration: