From 5d1b3669c50c99e439a56de00e67432464957bb8 Mon Sep 17 00:00:00 2001 From: Tobias Schultze Date: Mon, 21 May 2012 04:26:59 +0200 Subject: [PATCH] [Form] fix PhpDoc --- .../Component/Form/AbstractExtension.php | 30 +----- src/Symfony/Component/Form/AbstractType.php | 71 ++----------- .../Component/Form/AbstractTypeExtension.php | 38 +------ .../Component/Form/DataMapperInterface.php | 6 ++ .../Core/DataMapper/PropertyPathMapper.php | 14 ++- .../Form/Extension/Csrf/CsrfExtension.php | 2 +- .../Csrf/CsrfProvider/DefaultCsrfProvider.php | 6 +- .../Csrf/CsrfProvider/SessionCsrfProvider.php | 14 +-- .../Component/Form/FormExtensionInterface.php | 2 + src/Symfony/Component/Form/FormFactory.php | 99 ++----------------- .../Component/Form/FormFactoryInterface.php | 47 +++++++-- .../Form/FormTypeExtensionInterface.php | 6 +- .../Component/Form/FormTypeInterface.php | 4 +- 13 files changed, 95 insertions(+), 244 deletions(-) diff --git a/src/Symfony/Component/Form/AbstractExtension.php b/src/Symfony/Component/Form/AbstractExtension.php index 4f4c2774a1..4b309354a4 100644 --- a/src/Symfony/Component/Form/AbstractExtension.php +++ b/src/Symfony/Component/Form/AbstractExtension.php @@ -44,13 +44,7 @@ abstract class AbstractExtension implements FormExtensionInterface private $typeGuesserLoaded = false; /** - * Returns a type by name. - * - * @param string $name The name of the type - * - * @return FormTypeInterface The type - * - * @throws FormException if the given type is not supported by this extension + * {@inheritdoc} */ public function getType($name) { @@ -66,11 +60,7 @@ abstract class AbstractExtension implements FormExtensionInterface } /** - * Returns whether the given type is supported. - * - * @param string $name The name of the type - * - * @return Boolean Whether the type is supported by this extension + * {@inheritdoc} */ public function hasType($name) { @@ -82,11 +72,7 @@ abstract class AbstractExtension implements FormExtensionInterface } /** - * Returns the extensions for the given type. - * - * @param string $name The name of the type - * - * @return array An array of extensions as FormTypeExtensionInterface instances + * {@inheritdoc} */ public function getTypeExtensions($name) { @@ -100,11 +86,7 @@ abstract class AbstractExtension implements FormExtensionInterface } /** - * Returns whether this extension provides type extensions for the given type. - * - * @param string $name The name of the type - * - * @return Boolean Whether the given type has extensions + * {@inheritdoc} */ public function hasTypeExtensions($name) { @@ -116,9 +98,7 @@ abstract class AbstractExtension implements FormExtensionInterface } /** - * Returns the type guesser provided by this extension. - * - * @return FormTypeGuesserInterface|null The type guesser + * {@inheritdoc} */ public function getTypeGuesser() { diff --git a/src/Symfony/Component/Form/AbstractType.php b/src/Symfony/Component/Form/AbstractType.php index 7552dd12f7..7b3a8e6ae3 100644 --- a/src/Symfony/Component/Form/AbstractType.php +++ b/src/Symfony/Component/Form/AbstractType.php @@ -22,67 +22,28 @@ abstract class AbstractType implements FormTypeInterface private $extensions = array(); /** - * Builds the form. - * - * 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 + * {@inheritdoc} */ public function buildForm(FormBuilder $builder, array $options) { } /** - * Builds the form view. - * - * 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 + * {@inheritdoc} */ public function buildView(FormView $view, FormInterface $form) { } /** - * Builds the form view. - * - * 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 + * {@inheritdoc} */ public function buildViewBottomUp(FormView $view, FormInterface $form) { } /** - * Returns a builder for the current type. - * - * 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 + * {@inheritdoc} */ public function createBuilder($name, FormFactoryInterface $factory, array $options) { @@ -90,9 +51,7 @@ abstract class AbstractType implements FormTypeInterface } /** - * Returns the default options for this type. - * - * @return array The default options + * {@inheritdoc} */ public function getDefaultOptions() { @@ -100,9 +59,7 @@ abstract class AbstractType implements FormTypeInterface } /** - * Returns the allowed option values for each option (if any). - * - * @return array The allowed option values + * {@inheritdoc} */ public function getAllowedOptionValues() { @@ -110,11 +67,7 @@ abstract class AbstractType implements FormTypeInterface } /** - * Returns the name of the parent type. - * - * @param array $options - * - * @return string|null The name of the parent type if any otherwise null + * {@inheritdoc} */ public function getParent(array $options) { @@ -122,11 +75,7 @@ abstract class AbstractType implements FormTypeInterface } /** - * Adds extensions for this type. - * - * @param array $extensions An array of FormTypeExtensionInterface - * - * @throws UnexpectedTypeException if any extension does not implement FormTypeExtensionInterface + * {@inheritdoc} */ public function setExtensions(array $extensions) { @@ -140,9 +89,7 @@ abstract class AbstractType implements FormTypeInterface } /** - * Returns the extensions associated with this type. - * - * @return array An array of FormTypeExtensionInterface + * {@inheritdoc} */ public function getExtensions() { diff --git a/src/Symfony/Component/Form/AbstractTypeExtension.php b/src/Symfony/Component/Form/AbstractTypeExtension.php index 21d441c729..d70054f097 100644 --- a/src/Symfony/Component/Form/AbstractTypeExtension.php +++ b/src/Symfony/Component/Form/AbstractTypeExtension.php @@ -14,54 +14,28 @@ namespace Symfony\Component\Form; abstract class AbstractTypeExtension implements FormTypeExtensionInterface { /** - * Builds the form. - * - * 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 + * {@inheritdoc} */ public function buildForm(FormBuilder $builder, array $options) { } /** - * Builds the view. - * - * 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 + * {@inheritdoc} */ public function buildView(FormView $view, FormInterface $form) { } /** - * Builds the view. - * - * 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 + * {@inheritdoc} */ public function buildViewBottomUp(FormView $view, FormInterface $form) { } /** - * Overrides the default options form the extended type. - * - * @return array + * {@inheritdoc} */ public function getDefaultOptions() { @@ -69,9 +43,7 @@ abstract class AbstractTypeExtension implements FormTypeExtensionInterface } /** - * Returns the allowed option values for each option (if any). - * - * @return array The allowed option values + * {@inheritdoc} */ public function getAllowedOptionValues() { diff --git a/src/Symfony/Component/Form/DataMapperInterface.php b/src/Symfony/Component/Form/DataMapperInterface.php index 68c8ad0b8d..a8b8fdffdd 100644 --- a/src/Symfony/Component/Form/DataMapperInterface.php +++ b/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); diff --git a/src/Symfony/Component/Form/Extension/Core/DataMapper/PropertyPathMapper.php b/src/Symfony/Component/Form/Extension/Core/DataMapper/PropertyPathMapper.php index c557d4a639..f8ccaaa2c9 100644 --- a/src/Symfony/Component/Form/Extension/Core/DataMapper/PropertyPathMapper.php +++ b/src/Symfony/Component/Form/Extension/Core/DataMapper/PropertyPathMapper.php @@ -31,10 +31,7 @@ class PropertyPathMapper implements DataMapperInterface } /** - * @param dataClass $data - * @param array $forms - * - * @throws UnexpectedTypeException if the type of the data parameter is not supported + * {@inheritdoc} */ 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'); diff --git a/src/Symfony/Component/Form/Extension/Csrf/CsrfExtension.php b/src/Symfony/Component/Form/Extension/Csrf/CsrfExtension.php index 5330bbda45..71d06381ad 100644 --- a/src/Symfony/Component/Form/Extension/Csrf/CsrfExtension.php +++ b/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 { diff --git a/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/DefaultCsrfProvider.php b/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/DefaultCsrfProvider.php index 1285653488..04194a19f0 100644 --- a/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/DefaultCsrfProvider.php +++ b/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() { diff --git a/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/SessionCsrfProvider.php b/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/SessionCsrfProvider.php index 5174412a97..da476b6902 100644 --- a/src/Symfony/Component/Form/Extension/Csrf/CsrfProvider/SessionCsrfProvider.php +++ b/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 - * - * @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 - * - * Automatically starts the session if necessary. - * - * @return string The session ID + * {@inheritdoc} */ protected function getSessionId() { diff --git a/src/Symfony/Component/Form/FormExtensionInterface.php b/src/Symfony/Component/Form/FormExtensionInterface.php index f20b681333..e3c2b78b96 100644 --- a/src/Symfony/Component/Form/FormExtensionInterface.php +++ b/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); diff --git a/src/Symfony/Component/Form/FormFactory.php b/src/Symfony/Component/Form/FormFactory.php index ab600c52be..f97c9536a1 100644 --- a/src/Symfony/Component/Form/FormFactory.php +++ b/src/Symfony/Component/Form/FormFactory.php @@ -61,11 +61,7 @@ class FormFactory implements FormFactoryInterface } /** - * Returns whether the given type is supported. - * - * @param string $name The name of the type - * - * @return Boolean Whether the type is supported + * {@inheritdoc} */ public function hasType($name) { @@ -83,9 +79,7 @@ class FormFactory implements FormFactoryInterface } /** - * Add a type. - * - * @param FormTypeInterface $type The type + * {@inheritdoc} */ public function addType(FormTypeInterface $type) { @@ -97,15 +91,7 @@ class FormFactory implements FormFactoryInterface } /** - * Returns a type by name. - * - * 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 + * {@inheritdoc} */ public function getType($name) { @@ -121,18 +107,7 @@ class FormFactory implements FormFactoryInterface } /** - * Returns a form. - * - * @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 + * {@inheritdoc} */ public function create($type, $data = null, array $options = array(), FormBuilder $parent = null) { @@ -140,19 +115,7 @@ class FormFactory implements FormFactoryInterface } /** - * 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 - * - * @throws FormException if any given option is not applicable to the given type + * {@inheritdoc} */ 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. - * - * @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 + * {@inheritdoc} */ 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 - * - * @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 + * {@inheritdoc} */ public function createBuilder($type, $data = null, array $options = array(), FormBuilder $parent = null) { @@ -199,17 +141,7 @@ class FormFactory implements FormFactoryInterface } /** - * Returns a form builder. - * - * @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 + * {@inheritdoc} */ 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. - * - * 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 + * {@inheritdoc} */ public function createBuilderForProperty($class, $property, $data = null, array $options = array(), FormBuilder $parent = null) { diff --git a/src/Symfony/Component/Form/FormFactoryInterface.php b/src/Symfony/Component/Form/FormFactoryInterface.php index 8463ed85ef..84037527f0 100644 --- a/src/Symfony/Component/Form/FormFactoryInterface.php +++ b/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); } diff --git a/src/Symfony/Component/Form/FormTypeExtensionInterface.php b/src/Symfony/Component/Form/FormTypeExtensionInterface.php index c4803f8664..24fb8a871d 100644 --- a/src/Symfony/Component/Form/FormTypeExtensionInterface.php +++ b/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 */ diff --git a/src/Symfony/Component/Form/FormTypeInterface.php b/src/Symfony/Component/Form/FormTypeInterface.php index aeb827baae..1c5eb9ad56 100644 --- a/src/Symfony/Component/Form/FormTypeInterface.php +++ b/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);