[symfony#1684] Adding the index/map, proofreading and adding a little bit more to the new serializer component doc

weaverryan · weaverryan · commit 39e9632d6df3 · 2012-09-13T20:38:26.000-05:00
diff --git a/components/index.rst b/components/index.rst
@@ -16,6 +16,7 @@ The Components
     locale
     process
     routing
+    serializer
     templating
     yaml
 
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -57,6 +57,10 @@
 
   * :doc:`/components/routing`
 
+* **The Serializer Component**
+
+  * :doc:`/components/serializer`
+
 * **The Templating Component**
 
   * :doc:`/components/templating`
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -5,19 +5,23 @@
 The Serializer Component
 ========================
 
-   The Serializer Component is meant to be used to turn Objects into a
+   The Serializer Component is meant to be used to turn objects into a
    specific format (XML, JSON, Yaml, ...) and the other way around.
 
-In order to do so, the Serializer Components follows the following
+In order to do so, the Serializer Component follows the following
 simple schema.
 
 .. image:: /images/components/serializer/serializer_workflow.png
 
 As you can see in the picture above, an array is used as a man in
-the middle. This way, Normalizers will only deal with turning specific
+the middle. This way, Serializers will only deal with turning specific
 **formats** into **arrays** and vice versa. The same way, Normalizers 
 will deal with turning specific **objects** into **arrays** and vice versa.
 
+Serialization is a complicated topic, and while this component may not work
+in all cases, it can be a useful tool while developing tools to serialize
+and deserialize your objects.
+
 Installation
 ------------
 
@@ -31,24 +35,23 @@ Usage
 -----
 
 Using the Serializer component is really simple. We just need to set up
-the  :class:`Symfony\\Component\\Serializer\\Serializer` specifying
-what Encoders and Normalizer are going to be available::
+the :class:`Symfony\\Component\\Serializer\\Serializer` specifying
+which Encoders and Normalizer are going to be available::
 
     use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Encoder\XmlEncoder;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
 
-    $encoders = array(new XmlEncoder(), new JsonEncoder() );
+    $encoders = array(new XmlEncoder(), new JsonEncoder());
     $normalizers = array(new GetSetMethodNormalizer());
 
     $serializer = new Serializer($normalizers, $encoders);
 
-
 Serializing an object
 ~~~~~~~~~~~~~~~~~~~~~
 
-For the sake of this example, let's ssume the following class already
+For the sake of this example, let's assume the following class already
 exists in our project::
 
     namespace Acme;
@@ -90,12 +93,12 @@ use the Serializer service created before::
 
     $serializer->serialize($person, 'json'); // Output: {"name":"foo","age":99}
 
-The first paramater of the `Serializer::serialize` is the object to be
-serialized, the second one will be used to pick the proper encoder,
+The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::serialize`
+is the object to be serialized and the second is used to choose the proper encoder,
 in this case :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`.
 
-Deserializing an object
-~~~~~~~~~~~~~~~~~~~~~~~~ 
+Deserializing an Object
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Let's see now how to do the exactly the opposite. This time, the information
 of the `People` class would be encoded in XML format::
@@ -109,8 +112,20 @@ of the `People` class would be encoded in XML format::
 
     $person = $serializer->deserialize($data,'Acme\Person','xml');
 
-In this case, `Serializer::deserialize` needs three parameters:
+In this case, :method:`Symfony\\Component\\Serializer\\Serializer::deserialize`
+needs three parameters:
 
 1. The information to be decoded
 2. The name of the class this information will be decoded to
 3. The encoder used to convert that information into an array
+
+JMSSerializationBundle
+----------------------
+
+A popular third-party bundle, `JMSSerializationBundle`_ exists and extends
+(and sometimes replaces) the serialization functionality. This includes the
+ability to configure how your objects should be serialize/deserialized via
+annotations (as well as YML, XML and PHP), integration with the Doctrine ORM,
+and handling of other complex cases (e.g. circular references).
+
+.. _`JMSSerializationBundle`: https://github.com/schmittjoh/JMSSerializerBundle
