From b1e14b27ba1cc582533f2492f828186bcfb82573 Mon Sep 17 00:00:00 2001
From: Felicitus <felicitus@felicitus.org>
Date: Wed, 27 Mar 2013 14:18:54 +0100
Subject: [PATCH] [master] Better documentation for

---
 .../Serializer/Encoder/DecoderInterface.php   | 12 ++++--
 .../Serializer/Encoder/JsonDecode.php         | 39 +++++++++++++++++--
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/src/Symfony/Component/Serializer/Encoder/DecoderInterface.php b/src/Symfony/Component/Serializer/Encoder/DecoderInterface.php
index ffd221fe8d..b94ce35c6d 100644
--- a/src/Symfony/Component/Serializer/Encoder/DecoderInterface.php
+++ b/src/Symfony/Component/Serializer/Encoder/DecoderInterface.php
@@ -21,16 +21,20 @@ interface DecoderInterface
     /**
      * Decodes a string into PHP data
      *
-     * @param scalar $data   Data to decode
-     * @param string $format Format name
-     * @param array  $context options that decoders have access to.
+     * @param scalar $data      Data to decode
+     * @param string $format    Format name
+     * @param array  $context   options that decoders have access to.
+     *
+     * The format parameter specifies which format the data is in; valid values depend on the specific implementation.
+     * Authors implementing this interface are encouraged to document which formats they support in a non-inherited
+     * phpdoc comment.
      *
      * @return mixed
      */
     public function decode($data, $format, array $context = array());
 
     /**
-     * Checks whether the serializer can decode from given format
+     * Checks whether the deserializer can decode from given format
      *
      * @param string $format format name
      *
diff --git a/src/Symfony/Component/Serializer/Encoder/JsonDecode.php b/src/Symfony/Component/Serializer/Encoder/JsonDecode.php
index e7cd9e073d..72a72335ba 100644
--- a/src/Symfony/Component/Serializer/Encoder/JsonDecode.php
+++ b/src/Symfony/Component/Serializer/Encoder/JsonDecode.php
@@ -18,15 +18,31 @@ namespace Symfony\Component\Serializer\Encoder;
  */
 class JsonDecode implements DecoderInterface
 {
+    /**
+     * Specifies if the returned result should be an associative array or a nested stdClass object hierarchy
+     * @var bool
+     */
     private $associative;
+
+    /**
+     * Specifies the recursion depth
+     * @var int
+     */
     private $recursionDepth;
+
     private $lastError = JSON_ERROR_NONE;
     protected $serializer;
 
+    /**
+     * Constructs a new JsonDecode instance.
+     *
+     * @param bool $associative True to return the result associative array, false for a nested stdClass hierarchy.
+     * @param int  $depth       Specifies the recursion depth
+     */
     public function __construct($associative = false, $depth = 512)
     {
         $this->associative = $associative;
-        $this->recursionDepth = $depth;
+        $this->recursionDepth = (int)$depth;
     }
 
     /**
@@ -42,12 +58,27 @@ class JsonDecode implements DecoderInterface
     }
 
     /**
-     * Decodes a JSON string into PHP data
+     * @param string $data      The encoded JSON string to decode
+     * @param string $format    Must be set to JsonEncoder::FORMAT
+     * @param array  $context   An optional set of options for the JSON decoder; see below.
      *
-     * @param string $data JSON
-     * @param string $format
+     * The $context array is a simple key=>value array, with the following supported keys:
+     *
+     * json_decode_associative: boolean
+     *      If true, returns the object as associative array.
+     *      If false, returns the object as nested StdClass
+     *      If not specified, this method will use the default set in JsonDecode::__construct
+     *
+     * json_decode_recursion_depth: integer
+     *      Specifies the maximum recursion depth
+     *      If not specified, this method will use the default set in JsonDecode::__construct
+     *
+     * json_decode_options: integer
+     *      Specifies additional options as per documentation for json_decode. Only supported with PHP 5.4.0 and higher.
      *
      * @return mixed
+     *
+     * @see http://php.net/json_decode json_decode
      */
     public function decode($data, $format, array $context = array())
     {