changed docs a bit

Annotation/Groups.php

@@ -26,13 +26,19 @@ use JMS\SerializerBundle\Exception\InvalidArgumentException;
  */
 final class Groups
 {
+    /** @var array<string> @Required */
     public $groups;
 
-    public function __construct(array $values)
+    public function __construct()
     {
-        if (!isset($values['value']) || !is_array($values['value'])) {
-            throw new InvalidArgumentException('$groups must be a array.');
+        if (0 === func_num_args()) {
+            return;
         }
-        $this->groups = $values['value'];
+        $values = func_get_arg(0);
+
+        if (!isset($values['value'])) {
+            throw new InvalidArgumentException('The "groups" attribute must be set.');
+        }
+        $this->groups = (array) $values['value'];
     }
 }

Resources/doc/cookbook/exclusion_strategies.rst

@@ -1,7 +1,17 @@
-Defining which properties should be serialized
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Exclusion Strategies
+====================
 
-The default exclusion policy is to exclude nothing, that is all properties of the
+Introduction
+------------
+The serializer supports different exclusion strategies. Each strategy allows
+you to define which properties of your objects should be serialized.
+
+General Exclusion Strategies
+----------------------------
+If you would like to always expose, or exclude certain properties. Then, you can
+do this with the annotations ``@ExclusionPolicy``, ``@Exclude``, and ``@Expose``.
+
+The default exclusion policy is to exclude nothing. That is, all properties of the
 object will be serialized. If you only want to expose a few of the properties,
 then it is easier to change the exclusion policy, and only mark these few properties:
 
@@ -27,4 +37,86 @@ then it is easier to change the exclusion policy, and only mark these few proper
          * @Expose
          */
         private $name;
-    }
+    }
+
+.. note ::
+
+    A property that is excluded by ``@Exclude`` cannot be exposed anymore by any
+    of the following strategies, but is always hidden.
+
+Versioning Objects
+------------------
+JMSSerializerBundle comes by default with a very neat feature which allows
+you to add versioning support to your objects, e.g. if you want to
+expose them via an API that is consumed by a third-party:
+
+.. code-block :: php
+
+    <?php
+
+    class VersionedObject
+    {
+        /**
+         * @Until("1.0.x")
+         */
+        private $name;
+
+        /**
+         * @Since("1.1")
+         * @SerializedName("name")
+         */
+        private $name2;
+    }
+    
+.. note ::
+
+    ``@Until``, and ``@Since`` both accept a standardized PHP version number.
+
+If you have annotated your objects like above, you can serializing different
+versions like this:
+
+.. code-block :: php
+
+    <?php
+
+    $serializer->setVersion('1.0');
+    $serializer->serialize(new VersionObject(), 'json');
+
+
+Creating Different Views of Your Objects
+----------------------------------------
+Another default exclusion strategy is to create different views of your objects.
+Let's say you would like to serialize your object in a different view depending
+whether it is displayed in a list view or in a details view.
+
+You can achieve that by using the ``@Groups`` annotation on your properties.
+
+.. code-block :: php
+
+    <?php 
+    
+    use JMS\SerializerBundle\Annotation\Groups;
+    
+    class BlogPost
+    {
+        /** @Groups({"list", "details"}) */
+        private $id;
+        
+        /** @Groups({"list", "details"}) */
+        private $title;
+        
+        /** @Groups({"list"}) */
+        private $nbComments;
+        
+        /** @Groups({"details"}) */
+        private $comments;
+    }
+    
+You can then tell the serializer which groups to serialize in your controller:
+
+.. code-block :: php
+
+    <?php
+    
+    $serializer->setGroups(array('list'));
+    $serializer->serialize(new BlogPost(), 'json');

Resources/doc/cookbook/metadata_for_third_party.rst

@@ -1,5 +1,5 @@
-Overriding Metadata
-~~~~~~~~~~~~~~~~~~~
+Overriding Metadata Provided by Third-Parties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes you want to serialize objects which are shipped by a third-party bundle. 
 Such a third-party bundle might not ship with metadata that suits your needs, or 

Resources/doc/cookbook/versioning_objects.rst

@@ -1,37 +0,0 @@
-Versioning Objects
-------------------
-JMSSerializerBundle comes by default with a very neat feature which allows
-you to add versioning support to your objects, e.g. if you want to
-expose them via an API that is consumed by a third-party:
-
-.. code-block :: php
-
-    <?php
-
-    class VersionedObject
-    {
-        /**
-         * @Until("1.0.x")
-         */
-        private $name;
-
-        /**
-         * @Since("1.1")
-         * @SerializedName("name")
-         */
-        private $name2;
-    }
-    
-.. note ::
-
-    ``@Until``, and ``@Since`` both accept a standardized PHP version number.
-
-If you have annotated your objects like above, you can serializing different
-versions like this:
-
-.. code-block :: php
-
-    <?php
-
-    $serializer->setVersion('1.0');
-    $serializer->serialize(new VersionObject(), 'json');

Resources/doc/index.rst

@@ -35,6 +35,7 @@ Documentation
 - Recipies
     * :doc:`Custom Handlers </cookbook/custom_handlers>`
     * :doc:`/cookbook/exclusion_strategies`
+    * :doc:`/cookbook/metadata_for_third_party`
 - Reference
     * :doc:`Annotations </reference/annotations>`
     * :doc:`XML Reference </reference/xml_reference>`

Resources/doc/reference/annotations.rst

@@ -47,16 +47,10 @@ excluded automatically. The version must be in a format that is understood by
 PHP's ``version_compare`` function.
 
 @Groups
--------
-
-This annotation can be defined on a property to specifiy if this porperty should 
-be serialized, if any group is specified with the 
-``$serializer->setGroups(array("Foo"))`` method. Both values always have to be 
-an array.
-
-.. code-block :: php
-
-  /** @Groups({"Foo","Bar"}) */
+~~~~~~~
+This annotation can be defined on a property to specifiy to if the property 
+should be serialized when only serializing specific groups (see 
+:doc:`../cookbook/exclusion_strategies`).
 
 @AccessType
 ~~~~~~~~~~~