feature: add the context key documentation and remove encoders documentation

Author: Simperfit

components/serializer.rst

@@ -605,7 +605,26 @@ There are several types of normalizers available:
 Encoders
 --------
 
-The Serializer component supports many formats out of the box:
+Encoders basically turn **arrays** into **formats** and vice versa.
+They implement
+:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` for
+encoding (array to format) and
+:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for
+decoding (format to array).
+
+You can add new encoders to a Serializer instance by using its second constructor argument::
+
+    use Symfony\Component\Serializer\Serializer;
+    use Symfony\Component\Serializer\Encoder\XmlEncoder;
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
+
+    $encoders = array(new XmlEncoder(), new JsonEncoder());
+    $serializer = new Serializer(array(), $encoders);
+
+Built-in Encoders
+~~~~~~~~~~~~~~~~~
+
+The Serializer component provides built-in encoders:
 
 :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`
     This class encodes and decodes data in JSON_.
@@ -623,6 +642,56 @@ The Serializer component supports many formats out of the box:
 All these encoders are enabled by default when using the Symfony Standard Edition
 with the serializer enabled.
 
+The ``JsonEncoder``
+~~~~~~~~~~~~~~~~~~~
+
+The ``JsonEncoder`` encodes to and decodes from JSON strings, based on the PHP
+:phpfunction:`json_encode` and :phpfunction:`json_decode` functions.
+
+The ``CsvEncoder``
+~~~~~~~~~~~~~~~~~~~
+
+The ``CsvEncoder`` encodes to and decodes from CSV.
+
+You can pass the context key ``as_collection`` in order to have the results always as a collection.
+
+The ``XmlEncoder``
+~~~~~~~~~~~~~~~~~~
+
+This encoder transforms arrays into XML and vice versa.
+
+For example, take an object normalized as following::
+
+    array('foo' => array(1, 2), 'bar' => true);
+
+The ``XmlEncoder`` will encode this object like that::
+
+    <?xml version="1.0"?>
+    <response>
+        <foo>1</foo>
+        <foo>2</foo>
+        <bar>1</bar>
+    </response>
+
+Be aware that this encoder will consider keys beginning with ``@`` as attributes::
+
+    $encoder = new XmlEncoder();
+    $encoder->encode(array('foo' => array('@bar' => 'value')));
+    // will return:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value" />
+    // </response>
+
+You can pass the context key ``as_collection`` in order to have the results always as a collection.
+
+The ``YamlEncoder``
+~~~~~~~~~~~~~~~~~~~
+
+This encoder requires the :doc:`Yaml Component </components/yaml>` and
+transforms from and to Yaml.
+
+
 .. _component-serializer-handling-circular-references:
 
 Handling Circular References

serializer.rst

@@ -203,7 +203,6 @@ take a look at how this bundle works.
 .. toctree::
     :maxdepth: 1
 
-    serializer/encoders
     serializer/custom_encoders
 
 .. _`APCu`: https://github.com/krakjoe/apcu

serializer/custom_encoders.rst

@@ -9,7 +9,7 @@ to transform any data to an array. Then, by leveraging *Encoders*, that data can
 be converted into any data-structure (e.g. JSON).
 
 The Component provides several built-in encoders that are described
-:doc:`in their own section </serializer/encoders>` but you may want
+:doc:`in the serializer component </components/serializer>` but you may want
 to use another structure that's not supported.
 
 Creating a new encoder