merged branch Tobion/form-phpdoc (PR #4353)

Commits
-------

5d1b366 [Form] fix PhpDoc

Discussion
----------

[Form] fix PhpDoc

---------------------------------------------------------------------------

by travisbot at 2012-05-21T02:31:56Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1385372) (merged 5d1b3669 into 1407f112).

---------------------------------------------------------------------------

by vicb at 2012-05-21T05:44:03Z

have you used inheritdoc (over inheritDoc) on purpose ? (I must admin I haven't followed the CS discussion very closely)

---------------------------------------------------------------------------

by Tobion at 2012-05-21T16:16:48Z

Yes, inheritdoc is used on symfony. It's also the recommended way of phpdoc itself (all lower-case).

src/Symfony/Component/Form/AbstractExtension.php

@@ -44,13 +44,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     private $typeGuesserLoaded = false;
 
     /**
-     * Returns a type by name.
+     * {@inheritdoc}
-     *
-     * @param string $name The name of the type
-     *
-     * @return FormTypeInterface The type
-     *
-     * @throws FormException if the given type is not supported by this extension
      */
     public function getType($name)
     {
@@ -66,11 +60,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     }
 
     /**
-     * Returns whether the given type is supported.
+     * {@inheritdoc}
-     *
-     * @param string $name The name of the type
-     *
-     * @return Boolean Whether the type is supported by this extension
      */
     public function hasType($name)
     {
@@ -82,11 +72,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     }
 
     /**
-     * Returns the extensions for the given type.
+     * {@inheritdoc}
-     *
-     * @param string $name The name of the type
-     *
-     * @return array An array of extensions as FormTypeExtensionInterface instances
      */
     public function getTypeExtensions($name)
     {
@@ -100,11 +86,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     }
 
     /**
-     * Returns whether this extension provides type extensions for the given type.
+     * {@inheritdoc}
-     *
-     * @param string $name The name of the type
-     *
-     * @return Boolean Whether the given type has extensions
      */
     public function hasTypeExtensions($name)
     {
@@ -116,9 +98,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     }
 
     /**
-     * Returns the type guesser provided by this extension.
+     * {@inheritdoc}
-     *
-     * @return FormTypeGuesserInterface|null The type guesser
      */
     public function getTypeGuesser()
     {

src/Symfony/Component/Form/AbstractType.php

@@ -22,67 +22,28 @@ abstract class AbstractType implements FormTypeInterface
     private $extensions = array();
 
     /**
-     * Builds the form.
+     * {@inheritdoc}
-     *
-     * This method gets called for each type in the hierarchy starting from the
-     * top most type.
-     * Type extensions can further modify the form.
-     *
-     * @see FormTypeExtensionInterface::buildForm()
-     *
-     * @param FormBuilder $builder The form builder
-     * @param array       $options The options
      */
     public function buildForm(FormBuilder $builder, array $options)
     {
     }
 
     /**
-     * Builds the form view.
+     * {@inheritdoc}
-     *
-     * This method gets called for each type in the hierarchy starting from the
-     * top most type.
-     * Type extensions can further modify the view.
-     *
-     * @see FormTypeExtensionInterface::buildView()
-     *
-     * @param FormView      $view The view
-     * @param FormInterface $form The form
      */
     public function buildView(FormView $view, FormInterface $form)
     {
     }
 
     /**
-     * Builds the form view.
+     * {@inheritdoc}
-     *
-     * This method gets called for each type in the hierarchy starting from the
-     * top most type.
-     * Type extensions can further modify the view.
-     *
-     * Children views have been built while this method gets called so you get
-     * a chance to modify them.
-     *
-     * @see FormTypeExtensionInterface::buildViewBottomUp()
-     *
-     * @param FormView      $view The view
-     * @param FormInterface $form The form
      */
     public function buildViewBottomUp(FormView $view, FormInterface $form)
     {
     }
 
     /**
-     * Returns a builder for the current type.
+     * {@inheritdoc}
-     *
-     * The builder is retrieved by going up in the type hierarchy when a type does
-     * not provide one.
-     *
-     * @param string               $name    The name of the builder
-     * @param FormFactoryInterface $factory The form factory
-     * @param array                $options The options
-     *
-     * @return FormBuilder|null A form builder or null when the type does not have a builder
      */
     public function createBuilder($name, FormFactoryInterface $factory, array $options)
     {
@@ -90,9 +51,7 @@ abstract class AbstractType implements FormTypeInterface
     }
 
     /**
-     * Returns the default options for this type.
+     * {@inheritdoc}
-     *
-     * @return array The default options
      */
     public function getDefaultOptions()
     {
@@ -100,9 +59,7 @@ abstract class AbstractType implements FormTypeInterface
     }
 
     /**
-     * Returns the allowed option values for each option (if any).
+     * {@inheritdoc}
-     *
-     * @return array The allowed option values
      */
     public function getAllowedOptionValues()
     {
@@ -110,11 +67,7 @@ abstract class AbstractType implements FormTypeInterface
     }
 
     /**
-     * Returns the name of the parent type.
+     * {@inheritdoc}
-     *
-     * @param array $options
-     *
-     * @return string|null The name of the parent type if any otherwise null
      */
     public function getParent(array $options)
     {
@@ -122,11 +75,7 @@ abstract class AbstractType implements FormTypeInterface
     }
 
     /**
-     * Adds extensions for this type.
+     * {@inheritdoc}
-     *
-     * @param array $extensions An array of FormTypeExtensionInterface
-     *
-     * @throws UnexpectedTypeException if any extension does not implement FormTypeExtensionInterface
      */
     public function setExtensions(array $extensions)
     {
@@ -140,9 +89,7 @@ abstract class AbstractType implements FormTypeInterface
     }
 
     /**
-     * Returns the extensions associated with this type.
+     * {@inheritdoc}
-     *
-     * @return array An array of FormTypeExtensionInterface
      */
     public function getExtensions()
     {

src/Symfony/Component/Form/AbstractTypeExtension.php

@@ -14,54 +14,28 @@ namespace Symfony\Component\Form;
 abstract class AbstractTypeExtension implements FormTypeExtensionInterface
 {
     /**
-     * Builds the form.
+     * {@inheritdoc}
-     *
-     * This method gets called after the extended type has built the form to
-     * further modify it.
-     *
-     * @see FormTypeInterface::buildForm()
-     *
-     * @param FormBuilder $builder The form builder
-     * @param array       $options The options
      */
     public function buildForm(FormBuilder $builder, array $options)
     {
     }
 
     /**
-     * Builds the view.
+     * {@inheritdoc}
-     *
-     * This method gets called after the extended type has built the view to
-     * further modify it.
-     *
-     * @see FormTypeInterface::buildView()
-     *
-     * @param FormView      $view The view
-     * @param FormInterface $form The form
      */
     public function buildView(FormView $view, FormInterface $form)
     {
     }
 
     /**
-     * Builds the view.
+     * {@inheritdoc}
-     *
-     * This method gets called after the extended type has built the view to
-     * further modify it.
-     *
-     * @see FormTypeInterface::buildViewBottomUp()
-     *
-     * @param FormView      $view The view
-     * @param FormInterface $form The form
      */
     public function buildViewBottomUp(FormView $view, FormInterface $form)
     {
     }
 
     /**
-     * Overrides the default options form the extended type.
+     * {@inheritdoc}
-     *
-     * @return array
      */
     public function getDefaultOptions()
     {
@@ -69,9 +43,7 @@ abstract class AbstractTypeExtension implements FormTypeExtensionInterface
     }
 
     /**
-     * Returns the allowed option values for each option (if any).
+     * {@inheritdoc}
-     *
-     * @return array The allowed option values
      */
     public function getAllowedOptionValues()
     {

src/Symfony/Component/Form/DataMapperInterface.php

@@ -13,6 +13,12 @@ namespace Symfony\Component\Form;
 
 interface DataMapperInterface
 {
+    /**
+     * @param dataClass $data
+     * @param array     $forms
+     *
+     * @throws Exception\UnexpectedTypeException if the type of the data parameter is not supported
+     */
     function mapDataToForms($data, array $forms);
 
     function mapDataToForm($data, FormInterface $form);

src/Symfony/Component/Form/Extension/Core/DataMapper/PropertyPathMapper.php

@@ -31,10 +31,7 @@ class PropertyPathMapper implements DataMapperInterface
     }
 
     /**
-     * @param dataClass $data
+     * {@inheritdoc}
-     * @param array     $forms
-     *
-     * @throws UnexpectedTypeException if the type of the data parameter is not supported
      */
     public function mapDataToForms($data, array $forms)
     {
@@ -56,6 +53,9 @@ class PropertyPathMapper implements DataMapperInterface
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function mapDataToForm($data, FormInterface $form)
     {
         if (!empty($data)) {
@@ -73,6 +73,9 @@ class PropertyPathMapper implements DataMapperInterface
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function mapFormsToData(array $forms, &$data)
     {
         $iterator = new VirtualFormAwareIterator($forms);
@@ -83,6 +86,9 @@ class PropertyPathMapper implements DataMapperInterface
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function mapFormToData(FormInterface $form, &$data)
     {
         $propertyPath = $form->getAttribute('property_path');

src/Symfony/Component/Form/Extension/Csrf/CsrfExtension.php

@@ -16,7 +16,7 @@ use Symfony\Component\Form\Extension\Csrf\CsrfProvider\CsrfProviderInterface;
 use Symfony\Component\Form\AbstractExtension;
 
 /**
- * This extension protects forms by using a CSRF token
+ * This extension protects forms by using a CSRF token.
  */
 class CsrfExtension extends AbstractExtension
 {

src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/DefaultCsrfProvider.php

@@ -12,7 +12,7 @@
 namespace Symfony\Component\Form\Extension\Csrf\CsrfProvider;
 
 /**
- * Default implementation of CsrfProviderInterface
+ * Default implementation of CsrfProviderInterface.
  *
  * This provider uses the session ID returned by session_id() as well as a
  * user-defined secret value to secure the CSRF token.
@@ -57,11 +57,11 @@ class DefaultCsrfProvider implements CsrfProviderInterface
     }
 
     /**
-     * Returns the ID of the user session
+     * Returns the ID of the user session.
      *
      * Automatically starts the session if necessary.
      *
-     * @return string  The session ID
+     * @return string The session ID
      */
     protected function getSessionId()
     {

src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/SessionCsrfProvider.php

@@ -15,11 +15,11 @@ use Symfony\Component\HttpFoundation\Session\Session;
 
 /**
  * This provider uses a Symfony2 Session object to retrieve the user's
- * session ID
+ * session ID.
+ *
+ * @see DefaultCsrfProvider
  *
  * @author Bernhard Schussek <bernhard.schussek@symfony.com>
- *
- * @see    DefaultCsrfProvider
  */
 class SessionCsrfProvider extends DefaultCsrfProvider
 {
@@ -30,7 +30,7 @@ class SessionCsrfProvider extends DefaultCsrfProvider
     protected $session;
 
     /**
-     * Initializes the provider with a Session object and a secret value
+     * Initializes the provider with a Session object and a secret value.
      *
      * A recommended value for the secret is a generated value with at least
      * 32 characters and mixed letters, digits and special characters.
@@ -46,11 +46,7 @@ class SessionCsrfProvider extends DefaultCsrfProvider
     }
 
     /**
-     * Returns the ID of the user session
+     * {@inheritdoc}
-     *
-     * Automatically starts the session if necessary.
-     *
-     * @return string  The session ID
      */
     protected function getSessionId()
     {

src/Symfony/Component/Form/FormExtensionInterface.php

@@ -22,6 +22,8 @@ interface FormExtensionInterface
      * @param string $name The name of the type
      *
      * @return FormTypeInterface The type
+     *
+     * @throws Exception\FormException if the given type is not supported by this extension
      */
     function getType($name);
 

src/Symfony/Component/Form/FormFactory.php

@@ -61,11 +61,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns whether the given type is supported.
+     * {@inheritdoc}
-     *
-     * @param string $name The name of the type
-     *
-     * @return Boolean Whether the type is supported
      */
     public function hasType($name)
     {
@@ -83,9 +79,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Add a type.
+     * {@inheritdoc}
-     *
-     * @param FormTypeInterface $type The type
      */
     public function addType(FormTypeInterface $type)
     {
@@ -97,15 +91,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a type by name.
+     * {@inheritdoc}
-     *
-     * This methods registers the type extensions from the form extensions.
-     *
-     * @param string|FormTypeInterface $name The name of the type or a type instance
-     *
-     * @return FormTypeInterface The type
-     *
-     * @throws FormException if the type can not be retrieved from any extension
      */
     public function getType($name)
     {
@@ -121,18 +107,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form.
+     * {@inheritdoc}
-     *
-     * @see createBuilder()
-     *
-     * @param string|FormTypeInterface $type    The type of the form
-     * @param mixed                    $data    The initial data
-     * @param array                    $options The options
-     * @param FormBuilder              $parent  The parent builder
-     *
-     * @return Form The form named after the type
-     *
-     * @throws FormException if any given option is not applicable to the given type
      */
     public function create($type, $data = null, array $options = array(), FormBuilder $parent = null)
     {
@@ -140,19 +115,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form.
+     * {@inheritdoc}
-     *
-     * @see createNamedBuilder()
-     *
-     * @param string|FormTypeInterface $type    The type of the form
-     * @param string                   $name    The name of the form
-     * @param mixed                    $data    The initial data
-     * @param array                    $options The options
-     * @param FormBuilder              $parent  The parent builder
-     *
-     * @return Form The form
-     *
-     * @throws FormException if any given option is not applicable to the given type
      */
     public function createNamed($type, $name, $data = null, array $options = array(), FormBuilder $parent = null)
     {
@@ -160,19 +123,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form for a property of a class.
+     * {@inheritdoc}
-     *
-     * @see createBuilderForProperty()
-     *
-     * @param string      $class    The fully qualified class name
-     * @param string      $property The name of the property to guess for
-     * @param mixed       $data     The initial data
-     * @param array       $options  The options for the builder
-     * @param FormBuilder $parent   The parent builder
-     *
-     * @return Form The form named after the property
-     *
-     * @throws FormException if any given option is not applicable to the form type
      */
     public function createForProperty($class, $property, $data = null, array $options = array(), FormBuilder $parent = null)
     {
@@ -180,16 +131,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form builder
+     * {@inheritdoc}
-     *
-     * @param string|FormTypeInterface $type    The type of the form
-     * @param mixed                    $data    The initial data
-     * @param array                    $options The options
-     * @param FormBuilder              $parent  The parent builder
-     *
-     * @return FormBuilder The form builder
-     *
-     * @throws FormException if any given option is not applicable to the given type
      */
     public function createBuilder($type, $data = null, array $options = array(), FormBuilder $parent = null)
     {
@@ -199,17 +141,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form builder.
+     * {@inheritdoc}
-     *
-     * @param string|FormTypeInterface $type    The type of the form
-     * @param string                   $name    The name of the form
-     * @param mixed                    $data    The initial data
-     * @param array                    $options The options
-     * @param FormBuilder              $parent  The parent builder
-     *
-     * @return FormBuilder The form builder
-     *
-     * @throws FormException if any given option is not applicable to the given type
      */
     public function createNamedBuilder($type, $name, $data = null, array $options = array(), FormBuilder $parent = null)
     {
@@ -305,20 +237,7 @@ class FormFactory implements FormFactoryInterface
     }
 
     /**
-     * Returns a form builder for a property of a class.
+     * {@inheritdoc}
-     *
-     * If any of the 'max_length', 'required', 'pattern' and type options can be guessed,
-     * and are not provided in the options argument, the guessed value is used.
-     *
-     * @param string      $class    The fully qualified class name
-     * @param string      $property The name of the property to guess for
-     * @param mixed       $data     The initial data
-     * @param array       $options  The options for the builder
-     * @param FormBuilder $parent   The parent builder
-     *
-     * @return FormBuilder The form builder named after the property
-     *
-     * @throws FormException if any given option is not applicable to the form type
      */
     public function createBuilderForProperty($class, $property, $data = null, array $options = array(), FormBuilder $parent = null)
     {

src/Symfony/Component/Form/FormFactoryInterface.php

@@ -23,44 +23,48 @@ interface FormFactoryInterface
      * @param array                    $options The options
      * @param FormBuilder              $parent  The parent builder
      *
-     * @return Form The form named after the type
+     * @return FormInterface The form named after the type
      *
-     * @throws FormException if any given option is not applicable to the given type
+     * @throws Exception\FormException if any given option is not applicable to the given type
      */
     function create($type, $data = null, array $options = array(), FormBuilder $parent = null);
 
     /**
      * Returns a form.
      *
+     * @see createNamedBuilder()
+     *
      * @param string|FormTypeInterface $type    The type of the form
      * @param string                   $name    The name of the form
      * @param mixed                    $data    The initial data
      * @param array                    $options The options
      * @param FormBuilder              $parent  The parent builder
      *
-     * @return Form The form
+     * @return FormInterface The form
      *
-     * @throws FormException if any given option is not applicable to the given type
+     * @throws Exception\FormException if any given option is not applicable to the given type
      */
     function createNamed($type, $name, $data = null, array $options = array(), FormBuilder $parent = null);
 
     /**
      * Returns a form for a property of a class.
      *
+     * @see createBuilderForProperty()
+     *
      * @param string      $class    The fully qualified class name
      * @param string      $property The name of the property to guess for
      * @param mixed       $data     The initial data
      * @param array       $options  The options for the builder
      * @param FormBuilder $parent   The parent builder
      *
-     * @return Form The form named after the property
+     * @return FormInterface The form named after the property
      *
-     * @throws FormException if any given option is not applicable to the form type
+     * @throws Exception\FormException if any given option is not applicable to the form type
      */
     function createForProperty($class, $property, $data = null, array $options = array(), FormBuilder $parent = null);
 
     /**
-     * Returns a form builder
+     * Returns a form builder.
      *
      * @param string|FormTypeInterface $type    The type of the form
      * @param mixed                    $data    The initial data
@@ -69,7 +73,7 @@ interface FormFactoryInterface
      *
      * @return FormBuilder The form builder
      *
-     * @throws FormException if any given option is not applicable to the given type
+     * @throws Exception\FormException if any given option is not applicable to the given type
      */
     function createBuilder($type, $data = null, array $options = array(), FormBuilder $parent = null);
 
@@ -84,7 +88,7 @@ interface FormFactoryInterface
      *
      * @return FormBuilder The form builder
      *
-     * @throws FormException if any given option is not applicable to the given type
+     * @throws Exception\FormException if any given option is not applicable to the given type
      */
     function createNamedBuilder($type, $name, $data = null, array $options = array(), FormBuilder $parent = null);
 
@@ -102,13 +106,36 @@ interface FormFactoryInterface
      *
      * @return FormBuilder The form builder named after the property
      *
-     * @throws FormException if any given option is not applicable to the form type
+     * @throws Exception\FormException if any given option is not applicable to the form type
      */
     function createBuilderForProperty($class, $property, $data = null, array $options = array(), FormBuilder $parent = null);
 
+    /**
+     * Returns a type by name.
+     *
+     * This methods registers the type extensions from the form extensions.
+     *
+     * @param string $name The name of the type
+     *
+     * @return FormTypeInterface The type
+     *
+     * @throws Exception\FormException if the type can not be retrieved from any extension
+     */
     function getType($name);
 
+    /**
+     * Returns whether the given type is supported.
+     *
+     * @param string $name The name of the type
+     *
+     * @return Boolean Whether the type is supported
+     */
     function hasType($name);
 
+    /**
+     * Adds a type.
+     *
+     * @param FormTypeInterface $type The type
+     */
     function addType(FormTypeInterface $type);
 }

src/Symfony/Component/Form/FormTypeExtensionInterface.php

@@ -55,8 +55,6 @@ interface FormTypeExtensionInterface
     /**
      * Overrides the default options form the extended type.
      *
-     * @param array $options
-     *
      * @return array
      */
     function getDefaultOptions();
@@ -64,15 +62,13 @@ interface FormTypeExtensionInterface
     /**
      * Returns the allowed option values for each option (if any).
      *
-     * @param array $options
-     *
      * @return array The allowed option values
      */
     function getAllowedOptionValues();
 
 
     /**
-     * Returns the name of the type being extended
+     * Returns the name of the type being extended.
      *
      * @return string The name of the type being extended
      */

src/Symfony/Component/Form/FormTypeInterface.php

@@ -103,11 +103,11 @@ interface FormTypeInterface
     function getName();
 
     /**
-     * Adds extensions for this type.
+     * Sets the extensions for this type.
      *
      * @param array $extensions An array of FormTypeExtensionInterface
      *
-     * @throws UnexpectedTypeException if any extension does not implement FormTypeExtensionInterface
+     * @throws Exception\UnexpectedTypeException if any extension does not implement FormTypeExtensionInterface
      */
     function setExtensions(array $extensions);