From 0d7c2272bc1062a91cab2e87d8fc47206fbd7850 Mon Sep 17 00:00:00 2001
From: Evan Villemez <evan.villemez@americancouncils.org>
Date: Tue, 28 Aug 2012 16:43:47 -0400
Subject: [PATCH] updated documentation to reflect return property, updated
 markdown formatter tests to reflect parameter readonly property

---
 Formatter/MarkdownFormatter.php           |  2 ++
 README.md                                 |  3 +++
 Resources/views/method.html.twig          | 28 +++++++++++++++++++++++
 Tests/Formatter/MarkdownFormatterTest.php | 14 ++++++++++++
 4 files changed, 47 insertions(+)

diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index 3126909..46a030c 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/Formatter/MarkdownFormatter.php
@@ -76,6 +76,7 @@ class MarkdownFormatter extends AbstractFormatter
                 $markdown .= sprintf("%s:\n\n", $name);
                 $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
                 $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+                $markdown .= sprintf("  * readonly: %s\n", $parameter['readonly'] ? 'true' : 'false');
 
                 if (isset($parameter['description']) && !empty($parameter['description'])) {
                     $markdown .= sprintf("  * description: %s\n", $parameter['description']);
@@ -92,6 +93,7 @@ class MarkdownFormatter extends AbstractFormatter
                 $markdown .= sprintf("%s:\n\n", $name);
                 $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
                 $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+                $markdown .= sprintf("  * readonly: %s\n", $parameter['readonly'] ? 'true' : 'false');
 
                 if (isset($parameter['description']) && !empty($parameter['description'])) {
                     $markdown .= sprintf("  * description: %s\n", $parameter['description']);
diff --git a/README.md b/README.md
index f669443..f7f044f 100644
--- a/README.md
+++ b/README.md
@@ -83,6 +83,7 @@ class YourController extends Controller
      * @ApiDoc(
      *  description="Create a new Object",
      *  input="Your\Namespace\Form\Type\YourType"
+     *  return='Your\Namespace\Class'
      * )
      */
     public function postAction()
@@ -101,6 +102,8 @@ The following properties are available:
 
 * `input`: the input type associated to the method, currently this supports Form Types, and classes with JMS Serializer
  metadata, useful for POST|PUT methods, either as FQCN or as form type (if it is registered in the form factory in the container)
+ 
+* `return`: the return type associated with the response.  Specified and parsed the same way as `input`.
 
 Each _filter_ has to define a `name` parameter, but other parameters are free. Filters are often optional
 parameters, and you can document them as you want, but keep in mind to be consistent for the whole documentation.
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index f7a1182..aab13ad 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -91,6 +91,7 @@
                             <th>Parameter</th>
                             <th>Type</th>
                             <th>Required?</th>
+                            <th>Read Only?</th>
                             <th>Description</th>
                         </tr>
                     </thead>
@@ -100,6 +101,33 @@
                                 <td>{{ name }}</td>
                                 <td>{{ infos.dataType }}</td>
                                 <td>{{ infos.required ? 'true' : 'false' }}</td>
+                                <td>{{ infos.readonly }} ? 'true' : 'false'</td>
+                                <td>{{ infos.description }}</td>
+                            </tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+            {% endif %}
+
+            {% if data.response is defined and data.response is not empty %}
+                <h4>Return</h4>
+                <table class='fullwidth'>
+                    <thead>
+                        <tr>
+                            <th>Parameter</th>
+                            <th>Type</th>
+                            <th>Required?</th>
+                            <th>Read Only?</th>
+                            <th>Description</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {% for name, infos in data.response %}
+                            <tr>
+                                <td>{{ name }}</td>
+                                <td>{{ infos.dataType }}</td>
+                                <td>{{ infos.required ? 'true' : 'false' }}</td>
+                                <td>{{ infos.readonly }} ? 'true' : 'false'</td>
                                 <td>{{ infos.description }}</td>
                             </tr>
                         {% endfor %}
diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php
index fc25e6b..dc8c6af 100644
--- a/Tests/Formatter/MarkdownFormatterTest.php
+++ b/Tests/Formatter/MarkdownFormatterTest.php
@@ -83,17 +83,20 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 b:
 
   * type: string
   * required: false
+  * readonly: false
 
 c:
 
   * type: boolean
   * required: true
+  * readonly: false
 
 
 ### `POST` /tests.{_format} ###
@@ -111,17 +114,20 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 b:
 
   * type: string
   * required: false
+  * readonly: false
 
 c:
 
   * type: boolean
   * required: true
+  * readonly: false
 
 
 
@@ -137,6 +143,7 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 
@@ -165,36 +172,42 @@ foo:
 
   * type: string
   * required: false
+  * readonly: false
   * description: No description.
 
 bar:
 
   * type: DateTime
   * required: false
+  * readonly: true
   * description: No description.
 
 number:
 
   * type: double
   * required: false
+  * readonly: false
   * description: No description.
 
 arr:
 
   * type: array
   * required: false
+  * readonly: false
   * description: No description.
 
 nested:
 
   * type: object (JmsNested)
   * required: false
+  * readonly: false
   * description: No description.
 
 nestedArray:
 
   * type: array of objects (JmsNested)
   * required: false
+  * readonly: false
   * description: No description.
 
 
@@ -208,6 +221,7 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description