added some doc comments

Metadata/ClassHierarchyMetadata.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata;
 
 class ClassHierarchyMetadata

Metadata/ClassMetadata.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata;
 
 class ClassMetadata implements \Serializable

Metadata/Driver/AnnotationDriver.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata\Driver;
 
 use Annotations\ReaderInterface;

Metadata/Driver/DriverInterface.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata\Driver;
 
 interface DriverInterface

Metadata/MetadataFactory.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata;
 
 use JMS\SerializerBundle\Metadata\Driver\DriverInterface;

Metadata/PropertyMetadata.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Metadata;
 
 class PropertyMetadata implements \Serializable

Serializer/Exclusion/AllExclusionStrategy.php

@@ -20,8 +20,16 @@ namespace JMS\SerializerBundle\Serializer\Exclusion;
 
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
+/**
+ * ExclusionStrategy implementation that skips all properties by default.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class AllExclusionStrategy implements ExclusionStrategyInterface
 {
+    /**
+     * {@inheritDoc}
+     */
     public function shouldSkipProperty(PropertyMetadata $property)
     {
         return !$property->isExposed();

Serializer/Exclusion/DisjunctExclusionStrategy.php

@@ -20,6 +20,13 @@ namespace JMS\SerializerBundle\Serializer\Exclusion;
 
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
+/**
+ * A short circuiting implementation of the ExclusionStrategyInterface.
+ *
+ * This strategy is used to wrap several different exclusion strategies.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class DisjunctExclusionStrategy implements ExclusionStrategyInterface
 {
     private $strategies;
@@ -29,6 +36,9 @@ class DisjunctExclusionStrategy implements ExclusionStrategyInterface
         $this->strategies = $strategies;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function shouldSkipProperty(PropertyMetadata $property)
     {
         foreach ($this->strategies as $strategy) {

Serializer/Exclusion/ExclusionStrategyFactory.php

@@ -20,6 +20,11 @@ namespace JMS\SerializerBundle\Serializer\Exclusion;
 
 use JMS\SerializerBundle\Exception\RuntimeException;
 
+/**
+ * ExclusionStrategyFactory implementation.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class ExclusionStrategyFactory implements ExclusionStrategyFactoryInterface
 {
     private $strategies;
@@ -29,6 +34,9 @@ class ExclusionStrategyFactory implements ExclusionStrategyFactoryInterface
         $this->strategies = $strategies;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getStrategy($name)
     {
         if (isset($this->strategies[$name])) {

Serializer/Exclusion/ExclusionStrategyFactoryInterface.php

@@ -18,7 +18,22 @@
 
 namespace JMS\SerializerBundle\Serializer\Exclusion;
 
+/**
+ * Exclusion Strategy Factory interface.
+ *
+ * This interface allows different classes to have different exclusion
+ * strategies.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 interface ExclusionStrategyFactoryInterface
 {
+    /**
+     * Returns the exclusion strategy factory to use.
+     *
+     * @param string $name
+     *
+     * @return ExclusionStrategyInterface
+     */
     function getStrategy($name);
 }

Serializer/Exclusion/ExclusionStrategyInterface.php

@@ -30,5 +30,12 @@ use JMS\SerializerBundle\Metadata\PropertyMetadata;
  */
 interface ExclusionStrategyInterface
 {
+    /**
+     * Whether the property should be skipped during the normalization process.
+     *
+     * @param PropertyMetadata $property
+     *
+     * @return boolean
+     */
     function shouldSkipProperty(PropertyMetadata $property);
 }

Serializer/Exclusion/NoneExclusionStrategy.php

@@ -20,8 +20,16 @@ namespace JMS\SerializerBundle\Serializer\Exclusion;
 
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
+/**
+ * Exclusion strategy excludes no property by default.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class NoneExclusionStrategy implements ExclusionStrategyInterface
 {
+    /**
+     * {@inheritDoc}
+     */
     public function shouldSkipProperty(PropertyMetadata $property)
     {
         return $property->isExcluded();

Serializer/Exclusion/VersionExclusionStrategy.php

@@ -20,7 +20,7 @@ namespace JMS\SerializerBundle\Serializer\Exclusion;
 
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
-class VersionExclusionStrategy
+class VersionExclusionStrategy implements ExclusionStrategyInterface
 {
     private $version;
 
@@ -29,6 +29,9 @@ class VersionExclusionStrategy
         $this->version = $version;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function shouldSkipProperty(PropertyMetadata $property)
     {
         if ((null !== $version = $property->getSinceVersion()) && version_compare($this->version, $version, '<')) {

Serializer/LazyLoadingSerializer.php

@@ -1,9 +1,30 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Serializer;
 
 use Symfony\Component\Serializer\SerializerAwareInterface;
 
+/**
+ * Serializer that supports lazy-loading encoders.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class LazyLoadingSerializer extends Serializer
 {
     private $container;

Serializer/Naming/CamelCaseNamingStrategy.php

@@ -20,6 +20,11 @@ namespace JMS\SerializerBundle\Serializer\Naming;
 
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
+/**
+ * Generic naming strategy which translates a camel-cased property name.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class CamelCaseNamingStrategy implements PropertyNamingStrategyInterface
 {
     private $separator;
@@ -31,6 +36,9 @@ class CamelCaseNamingStrategy implements PropertyNamingStrategyInterface
         $this->lowerCase = $lowerCase;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function translateName(PropertyMetadata $property)
     {
         $separator = &$this->separator;
@@ -38,9 +46,9 @@ class CamelCaseNamingStrategy implements PropertyNamingStrategyInterface
         $name = preg_replace('/[A-Z]/', $separator.'\\0', $property->getName());
 
         if ($this->lowerCase) {
-            $name = strtolower($name);
+            return strtolower($name);
         }
 
-        return $name;
+        return ucfirst($name);
     }
 }

Serializer/Naming/PropertyNamingStrategyInterface.php

@@ -30,5 +30,12 @@ use JMS\SerializerBundle\Metadata\PropertyMetadata;
  */
 interface PropertyNamingStrategyInterface
 {
+    /**
+     * Translates the name of the property to the serialized version.
+     *
+     * @param PropertyMetadata $property
+     *
+     * @return string
+     */
     function translateName(PropertyMetadata $property);
 }

Serializer/Naming/SerializedNameAnnotationStrategy.php

@@ -21,6 +21,11 @@ namespace JMS\SerializerBundle\Serializer\Naming;
 use JMS\SerializerBundle\Annotation\SerializedName;
 use JMS\SerializerBundle\Metadata\PropertyMetadata;
 
+/**
+ * Naming strategy which uses an annotation to translate the property name.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class SerializedNameAnnotationStrategy implements PropertyNamingStrategyInterface
 {
     private $delegate;
@@ -30,6 +35,9 @@ class SerializedNameAnnotationStrategy implements PropertyNamingStrategyInterfac
         $this->delegate = $namingStrategy;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function translateName(PropertyMetadata $property)
     {
         if (null !== $name = $property->getSerializedName()) {

Serializer/Normalizer/ArrayCollectionNormalizer.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Serializer\Normalizer;
 
 use JMS\SerializerBundle\Exception\UnsupportedException;
@@ -13,11 +29,17 @@ use Symfony\Component\Serializer\Normalizer\SerializerAwareNormalizer;
  */
 class ArrayCollectionNormalizer extends SerializerAwareNormalizer
 {
+    /**
+     * {@inheritDoc}
+     */
     public function normalize($data, $format = null)
     {
         throw new UnsupportedException('This normalizer is only used for denormalization.');
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function denormalize($data, $type, $format = null)
     {
         if (!is_array($data)) {
@@ -31,11 +53,17 @@ class ArrayCollectionNormalizer extends SerializerAwareNormalizer
         return new ArrayCollection($this->serializer->denormalize($data, 'array'.substr($type, 15), $format));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function supportsNormalization($data, $format = null)
     {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function supportsDenormalization($data, $type, $format = null)
     {
         return 0 === strpos($type, 'ArrayCollection<') && '>' === $type[strlen($type)-1];

Serializer/Normalizer/NativePhpTypeNormalizer.php

@@ -1,10 +1,31 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Serializer\Normalizer;
 
 use JMS\SerializerBundle\Exception\UnsupportedException;
 use Symfony\Component\Serializer\Normalizer\SerializerAwareNormalizer;
 
+/**
+ * Normalizer for native PHP types.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class NativePhpTypeNormalizer extends SerializerAwareNormalizer
 {
     private $dateTimeFormat;
@@ -14,6 +35,9 @@ class NativePhpTypeNormalizer extends SerializerAwareNormalizer
         $this->dateTimeFormat = $dateTimeFormat;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function normalize($data, $format = null)
     {
         if (null === $data || is_scalar($data)) {
@@ -35,24 +59,9 @@ class NativePhpTypeNormalizer extends SerializerAwareNormalizer
         throw new UnsupportedException(sprintf('"%s" is not supported.', gettype($data)));
     }
 
-    public function supportsNormalization($data, $format = null)
-    {
-        return null === $data
-               || is_scalar($data)
-               || is_array($data)
-               || $data instanceof \DateTime
-               || $data instanceof \Traversable;
-    }
-
-    public function supportsDenormalization($data, $type, $format = null)
-    {
-        return 'boolean' === $type
-               || 'integer' === $type
-               || 'string' === $type
-               || 'DateTime' === $type
-               || 0 === strpos($type, 'array');
-    }
-
+    /**
+     * {@inheritDoc}
+     */
     public function denormalize($data, $type, $format = null)
     {
         if ('boolean' === $type) {
@@ -105,4 +114,28 @@ class NativePhpTypeNormalizer extends SerializerAwareNormalizer
 
         throw new UnsupportedException(sprintf('Unsupported type "%s".', $type));
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function supportsNormalization($data, $format = null)
+    {
+        return null === $data
+               || is_scalar($data)
+               || is_array($data)
+               || $data instanceof \DateTime
+               || $data instanceof \Traversable;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function supportsDenormalization($data, $type, $format = null)
+    {
+        return 'boolean' === $type
+               || 'integer' === $type
+               || 'string' === $type
+               || 'DateTime' === $type
+               || 0 === strpos($type, 'array');
+    }
 }

Serializer/Normalizer/PropertyBasedNormalizer.php

@@ -30,6 +30,11 @@ use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 use Symfony\Component\Serializer\Normalizer\SerializerAwareNormalizer;
 
+/**
+ * Generic normalizer based on class properties.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class PropertyBasedNormalizer extends SerializerAwareNormalizer
 {
     private $metadataFactory;
@@ -43,6 +48,9 @@ class PropertyBasedNormalizer extends SerializerAwareNormalizer
         $this->exclusionStrategyFactory = $exclusionStrategyFactory;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function normalize($object, $format = null)
     {
         if (!is_object($object)) {
@@ -73,16 +81,9 @@ class PropertyBasedNormalizer extends SerializerAwareNormalizer
         return $normalized;
     }
 
-    public function supportsNormalization($data, $format = null)
-    {
-        return is_object($data);
-    }
-
-    public function supportsDenormalization($data, $type, $format = null)
-    {
-        return class_exists($type);
-    }
-
+    /**
+     * {@inheritDoc}
+     */
     public function denormalize($data, $type, $format = null)
     {
         if (!class_exists($type)) {
@@ -116,4 +117,20 @@ class PropertyBasedNormalizer extends SerializerAwareNormalizer
 
         return $object;
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function supportsNormalization($data, $format = null)
+    {
+        return is_object($data);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function supportsDenormalization($data, $type, $format = null)
+    {
+        return class_exists($type);
+    }
 }

Serializer/Serializer.php

@@ -1,5 +1,21 @@
 <?php
 
+/*
+ * Copyright 2011 Johannes M. Schmitt <schmittjoh@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 namespace JMS\SerializerBundle\Serializer;
 
 use Symfony\Component\Serializer\SerializerAwareInterface;
@@ -43,36 +59,49 @@ class Serializer implements SerializerInterface
         $this->encoderMap = $encoderMap;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function normalize($data, $format = null)
     {
         if ($this->nativePhpTypeNormalizer->supportsNormalization($data, $format)) {
             return $this->nativePhpTypeNormalizer->normalize($data, $format);
         }
 
-        foreach ($this->customObjectNormalizers as $normalizer) {
-            if ($normalizer->supportsNormalization($data, $format)) {
-                return $normalizer->normalize($data, $format);
+        if ($this->customObjectNormalizers) {
+            foreach ($this->customObjectNormalizers as $normalizer) {
+                if ($normalizer->supportsNormalization($data, $format)) {
+                    return $normalizer->normalize($data, $format);
+                }
             }
         }
 
         return $this->defaultObjectNormalizer->normalize($data, $format);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function denormalize($data, $type, $format = null)
     {
         if ($this->nativePhpTypeNormalizer->supportsDenormalization($data, $type, $format)) {
             return $this->nativePhpTypeNormalizer->denormalize($data, $type, $format);
         }
 
-        foreach ($this->customObjectNormalizers as $normalizer) {
-            if ($normalizer->supportsDenormalization($data, $type, $format)) {
-                return $normalizer->denormalize($data, $type, $format);
+        if ($this->customObjectNormalizers) {
+            foreach ($this->customObjectNormalizers as $normalizer) {
+                if ($normalizer->supportsDenormalization($data, $type, $format)) {
+                    return $normalizer->denormalize($data, $type, $format);
+                }
             }
         }
 
         return $this->defaultObjectNormalizer->denormalize($data, $type, $format);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function serialize($data, $format)
     {
         $data = $this->normalize($data, $format);
@@ -80,6 +109,9 @@ class Serializer implements SerializerInterface
         return $this->encode($data, $format);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function deserialize($data, $type, $format)
     {
         $data = $this->decode($data, $format);
@@ -87,11 +119,17 @@ class Serializer implements SerializerInterface
         return $this->denormalize($data, $type, $format);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function encode($data, $format)
     {
         return $this->getEncoder($format)->encode($data, $format);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public final function decode($data, $format)
     {
         return $this->getEncoder($format)->decode($data, $format);