Improve doc, update README, "return" param becomes "output" to be more

consistent

Annotation/ApiDoc.php

@@ -19,10 +19,26 @@ use Symfony\Component\Routing\Route;
 class ApiDoc
 {
     /**
+     * Requirements are mandatory parameters in a route.
+     *
+     * @var array
+     */
+    private $requirements = array();
+
+    /**
+     * Filters are optional parameters in the query string.
+     *
      * @var array
      */
     private $filters  = array();
 
+    /**
+     * Parameters are data a client can send.
+     *
+     * @var array
+     */
+    private $parameters = array();
+
     /**
      * @var string
      */
@@ -31,14 +47,18 @@ class ApiDoc
     /**
      * @var string
      */
-    private $return = null;
+    private $output = null;
 
     /**
+     * Most of the time, a single line of text describing the action.
+     *
      * @var string
      */
     private $description = null;
 
     /**
+     * Extended documentation.
+     *
      * @var string
      */
     private $documentation = null;
@@ -48,11 +68,6 @@ class ApiDoc
      */
     private $isResource = false;
 
-    /**
-     * @var array
-     */
-    private $requirements = array();
-
     /**
      * @var string
      */
@@ -63,11 +78,6 @@ class ApiDoc
      */
     private $uri;
 
-    /**
-     * @var array
-     */
-    private $parameters = array();
-
     /**
      * @var array
      */
@@ -85,6 +95,12 @@ class ApiDoc
 
     public function __construct(array $data)
     {
+        $this->isResource = isset($data['resource']) && $data['resource'];
+
+        if (isset($data['description'])) {
+            $this->description = $data['description'];
+        }
+
         if (isset($data['input'])) {
             $this->input = $data['input'];
         } elseif (isset($data['filters'])) {
@@ -100,19 +116,13 @@ class ApiDoc
             }
         }
 
-        if (isset($data['description'])) {
+        if (isset($data['output'])) {
-            $this->description = $data['description'];
+            $this->output = $data['output'];
-        }
-
-        if (isset($data['return'])) {
-            $this->return = $data['return'];
         }
 
         if (isset($data['statusCodes'])) {
             $this->statusCodes = $data['statusCodes'];
         }
-
-        $this->isResource = isset($data['resource']) && $data['resource'];
     }
 
     /**
@@ -152,9 +162,9 @@ class ApiDoc
     /**
      * @return string|null
      */
-    public function getReturn()
+    public function getOutput()
     {
-        return $this->return;
+        return $this->output;
     }
 
     /**
@@ -189,22 +199,6 @@ class ApiDoc
         return $this->isResource;
     }
 
-    /**
-     * @var string $method
-     */
-    public function setMethod($method)
-    {
-        $this->method = $method;
-    }
-
-    /**
-     * @var string $uri
-     */
-    public function setUri($uri)
-    {
-        $this->uri = $uri;
-    }
-
     /**
      * @param string $name
      * @param array  $parameter
@@ -232,20 +226,14 @@ class ApiDoc
         $this->response = $response;
     }
 
-    /**
-     * @return array
-     */
-    public function getResponse()
-    {
-        return $this->response;
-    }
-
     /**
      * @param Route $route
      */
     public function setRoute(Route $route)
     {
-        $this->route = $route;
+        $this->route  = $route;
+        $this->uri    = $route->getPattern();
+        $this->method = $route->getRequirement('_method') ?: 'ANY';
     }
 
     /**
@@ -256,22 +244,14 @@ class ApiDoc
         return $this->route;
     }
 
-    /**
-     * @return array
-     */
-    public function getStatusCodes()
-    {
-        return $this->statusCodes;
-    }
-
     /**
      * @return array
      */
     public function toArray()
     {
         $data = array(
-            'method'        => $this->method,
+            'method' => $this->method,
-            'uri'           => $this->uri,
+            'uri'    => $this->uri,
         );
 
         if ($description = $this->description) {

Extractor/ApiDocExtractor.php

@@ -22,34 +22,34 @@ use Nelmio\ApiDocBundle\Util\DocCommentExtractor;
 
 class ApiDocExtractor
 {
-    const ANNOTATION_CLASS      = 'Nelmio\\ApiDocBundle\\Annotation\\ApiDoc';
+    const ANNOTATION_CLASS              = 'Nelmio\\ApiDocBundle\\Annotation\\ApiDoc';
 
-    const FOS_REST_QUERY_PARAM_CLASS  = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam';
+    const FOS_REST_QUERY_PARAM_CLASS    = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam';
 
     const FOS_REST_REQUEST_PARAM_CLASS  = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam';
 
     /**
-     * @var \Symfony\Component\DependencyInjection\ContainerInterface
+     * @var ContainerInterface
      */
     protected $container;
 
     /**
-     * @var \Symfony\Component\Routing\RouterInterface
+     * @var RouterInterface
      */
     protected $router;
 
     /**
-     * @var \Doctrine\Common\Annotations\Reader
+     * @var Reader
      */
     protected $reader;
 
     /**
-     * @var \Nelmio\ApiDocBundle\Util\DocCommentExtractor
+     * @var DocCommentExtractor
      */
     private $commentExtractor;
 
     /**
-     * @var array \Nelmio\ApiDocBundle\Parser\ParserInterface
+     * @var array ParserInterface
      */
     protected $parsers = array();
 
@@ -265,13 +265,13 @@ class ApiDocExtractor
             $annotation->setParameters($parameters);
         }
 
-        // return (populates 'response' for the formatters)
+        // output (populates 'response' for the formatters)
-        if (null !== $return = $annotation->getReturn()) {
+        if (null !== $output = $annotation->getOutput()) {
             $response = array();
 
             foreach ($this->parsers as $parser) {
-                if ($parser->supports($return)) {
+                if ($parser->supports($output)) {
-                    $response = $parser->parse($return);
+                    $response = $parser->parse($output);
                     break;
                 }
             }
@@ -322,10 +322,6 @@ class ApiDocExtractor
 
         $annotation->setRequirements($requirements);
 
-        // method/uri
-        $annotation->setMethod($route->getRequirement('_method') ?: 'ANY');
-        $annotation->setUri($route->getPattern());
-
         return $annotation;
     }
 

README.md

@@ -83,7 +83,7 @@ class YourController extends Controller
      * @ApiDoc(
      *  description="Create a new Object",
      *  input="Your\Namespace\Form\Type\YourType",
-     *  return="Your\Namespace\Class"
+     *  output="Your\Namespace\Class"
      * )
      */
     public function postAction()
@@ -103,7 +103,7 @@ 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`.
+* `output`: the output type associated with the response.  Specified and parsed the same way as `input`.
 
 * `statusCodes`: an array of HTTP status codes and a description of when that status is returned; Example:
 

Tests/Fixtures/Controller/TestController.php

@@ -105,7 +105,7 @@ class TestController
     /**
      * @ApiDoc(
      *  description="Testing return",
-     *  return="dependency_type"
+     *  output="dependency_type"
      * )
      */
     public function jmsReturnTestAction()