diogo
/
symfony
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

merged branch Tobion/formdoc (PR #5350) 

Commits
-------

83dc966 [Form] Fixed some PHPDoc
596bbb1 [Form] fixed FormConfigBuilder to use PropertyPathInterface
a523823 [Form] fixed and added phpDoc

Discussion
----------

[Form] fixed and added phpDoc

[ci skip]

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

by sstok at 2012-08-26T08:11:01Z

Some descriptions don''t seem to be properly aligned, use the CS-fixer.

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

by Tobion at 2012-08-26T17:02:25Z

@sstok This is more about manual fixes concerning forgotten exceptions or wrong data type. The cs fixer gives many false positives and can be applied later.
This commit is contained in:
Fabien Potencier 2012-08-28 07:38:26 +02:00
parent f11d7a0a0c 83dc966f1c
commit 66a060defd
18 changed files with 116 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/Symfony/Bridge/Doctrine/Form/ChoiceList/ORMQueryBuilderLoader.php
View File

@ -33,9 +33,9 @@ class ORMQueryBuilderLoader implements EntityLoaderInterface
/**
* Construct an ORM Query Builder Loader
*
* @param QueryBuilder $queryBuilder
* @param EntityManager $manager
* @param string $class
* @param QueryBuilder|\Closure $queryBuilder
* @param EntityManager $manager
* @param string $class
*/
public function __construct($queryBuilder, $manager = null, $class = null)
{

1
src/Symfony/Bridge/Doctrine/Form/Type/DoctrineType.php
View File

@ -155,6 +155,7 @@ abstract class DoctrineType extends AbstractType
* @param ObjectManager $manager
* @param mixed $queryBuilder
* @param string $class
*
* @return EntityLoaderInterface
*/
abstract public function getLoader(ObjectManager $manager, $queryBuilder, $class);

2
src/Symfony/Component/Form/AbstractRendererEngine.php
View File

@ -22,7 +22,7 @@ abstract class AbstractRendererEngine implements FormRendererEngineInterface
* The variable in {@link FormView} used as cache key.
*/
const CACHE_KEY_VAR = 'cache_key';
/**
* @var array
*/

4
src/Symfony/Component/Form/Event/DataEvent.php
View File

@ -50,7 +50,7 @@ class DataEvent extends Event
/**
* Returns the data associated with this event.
*
* @return type
* @return mixed
*/
public function getData()
{
@ -58,7 +58,7 @@ class DataEvent extends Event
}
/**
* Allows updating with some filtered data
* Allows updating with some filtered data.
*
* @param mixed $data
*/

4
src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToBooleanArrayTransformer.php
View File

@ -77,7 +77,9 @@ class ChoiceToBooleanArrayTransformer implements DataTransformerInterface
*
* @return mixed A scalar value
*
* @throws new UnexpectedTypeException if the given value is not an array
* @throws UnexpectedTypeException if the given value is not an array
* @throws TransformationFailedException if the recuperation of the choices fails or
* if some choice can't be found
*/
public function reverseTransform($values)
{

6
src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoicesToBooleanArrayTransformer.php
View File

@ -40,7 +40,7 @@ class ChoicesToBooleanArrayTransformer implements DataTransformerInterface
*
* @return mixed An array
*
* @throws UnexpectedTypeException if the given value is not an array
* @throws UnexpectedTypeException if the given value is not an array
* @throws TransformationFailedException if the choices can not be retrieved
*/
public function transform($array)
@ -79,7 +79,9 @@ class ChoicesToBooleanArrayTransformer implements DataTransformerInterface
*
* @return mixed An array
*
* @throws UnexpectedTypeException if the given value is not an array
* @throws UnexpectedTypeException if the given value is not an array
* @throws TransformationFailedException if the recuperation of the choices fails or
* if some choice can't be found
*/
public function reverseTransform($values)
{

3
src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoicesToValuesTransformer.php
View File

@ -59,7 +59,8 @@ class ChoicesToValuesTransformer implements DataTransformerInterface
*
* @return array
*
* @throws UnexpectedTypeException if the given value is not an array
* @throws UnexpectedTypeException if the given value is not an array
* @throws TransformationFailedException if could not find all matching choices for the given values
*/
public function reverseTransform($array)
{

2
src/Symfony/Component/Form/Extension/Core/DataTransformer/PercentToLocalizedStringTransformer.php
View File

@ -42,6 +42,8 @@ class PercentToLocalizedStringTransformer implements DataTransformerInterface
*
* @param integer $precision The precision
* @param string $type One of the supported types
*
* @throws UnexpectedTypeException if the given value of type is unknown
*/
public function __construct($precision = null, $type = null)
{

117
src/Symfony/Component/Form/Form.php
View File

@ -143,6 +143,8 @@ class Form implements \IteratorAggregate, FormInterface
* Creates a new form based on the given configuration.
*
* @param FormConfigInterface $config The form configuration.
*
* @throws FormException if a data mapper is not provided for a compound form
*/
public function __construct(FormConfigInterface $config)
{
@ -164,9 +166,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the configuration of the form.
*
* @return FormConfigInterface The form's configuration.
* {@inheritdoc}
*/
public function getConfig()
{
@ -174,9 +174,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the name by which the form is identified in forms.
*
* @return string The name of the form.
* {@inheritdoc}
*/
public function getName()
{
@ -247,11 +245,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Sets the parent form.
*
* @param FormInterface $parent The parent form
*
* @return Form The current form
* {@inheritdoc}
*/
public function setParent(FormInterface $parent = null)
{
@ -269,9 +263,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the parent form.
*
* @return FormInterface The parent form
* {@inheritdoc}
*/
public function getParent()
{
@ -279,9 +271,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the form has a parent.
*
* @return Boolean
* {@inheritdoc}
*/
public function hasParent()
{
@ -289,9 +279,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the root of the form tree.
*
* @return FormInterface The root of the tree
* {@inheritdoc}
*/
public function getRoot()
{
@ -299,9 +287,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the form is the root of the form tree.
*
* @return Boolean
* {@inheritdoc}
*/
public function isRoot()
{
@ -339,11 +325,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Updates the form with default data.
*
* @param mixed $modelData The data formatted as expected for the underlying object
*
* @return Form The current form
* {@inheritdoc}
*/
public function setData($modelData)
{
@ -440,9 +422,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the data in the format needed for the underlying object.
*
* @return mixed
* {@inheritdoc}
*/
public function getData()
{
@ -454,11 +434,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the normalized data of the form.
*
* @return mixed When the form is not bound, the default data is returned.
* When the form is bound, the normalized bound data is
* returned if the form is valid, null otherwise.
* {@inheritdoc}
*/
public function getNormData()
{
@ -470,9 +446,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the data transformed by the value transformer.
*
* @return string
* {@inheritdoc}
*/
public function getViewData()
{
@ -497,9 +471,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the extra data.
*
* @return array The bound data which do not belong to a child
* {@inheritdoc}
*/
public function getExtraData()
{
@ -507,13 +479,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Binds data to the form, transforms and validates it.
*
* @param string|array $submittedData The data
*
* @return Form The current form
*
* @throws UnexpectedTypeException
* {@inheritdoc}
*/
public function bind($submittedData)
{
@ -677,11 +643,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Adds an error to this form.
*
* @param FormError $error
*
* @return Form The current form
* {@inheritdoc}
*/
public function addError(FormError $error)
{
@ -708,9 +670,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the form is bound.
*
* @return Boolean true if the form is bound to input values, false otherwise
* {@inheritdoc}
*/
public function isBound()
{
@ -718,9 +678,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the data in the different formats is synchronized.
*
* @return Boolean
* {@inheritdoc}
*/
public function isSynchronized()
{
@ -728,9 +686,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the form is empty.
*
* @return Boolean
* {@inheritdoc}
*/
public function isEmpty()
{
@ -744,9 +700,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns whether the form is valid.
*
* @return Boolean
* {@inheritdoc}
*/
public function isValid()
{
@ -783,9 +737,7 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns all errors.
*
* @return array An array of FormError instances that occurred during binding
* {@inheritdoc}
*/
public function getErrors()
{
@ -962,11 +914,11 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns true if the child exists (implements the \ArrayAccess interface).
* Returns whether a child with the given name exists (implements the \ArrayAccess interface).
*
* @param string $name The name of the child
*
* @return Boolean true if the widget exists, false otherwise
* @return Boolean
*/
public function offsetExists($name)
{
@ -974,11 +926,13 @@ class Form implements \IteratorAggregate, FormInterface
}
/**
* Returns the form child associated with the name (implements the \ArrayAccess interface).
* Returns the child with the given name (implements the \ArrayAccess interface).
*
* @param string $name The offset of the value to get
* @param string $name The name of the child
*
* @return FormInterface A form instance
* @return FormInterface The child form
*
* @throws \InvalidArgumentException If the named child does not exist.
*/
public function offsetGet($name)
{
@ -989,7 +943,12 @@ class Form implements \IteratorAggregate, FormInterface
* Adds a child to the form (implements the \ArrayAccess interface).
*
* @param string $name Ignored. The name of the child is used.
* @param FormInterface $child The child to be added
* @param FormInterface $child The child to be added.
*
* @throws AlreadyBoundException If the form has already been bound.
* @throws FormException When trying to add a child to a non-compound form.
*
* @see self::add()
*/
public function offsetSet($name, $child)
{
@ -999,7 +958,9 @@ class Form implements \IteratorAggregate, FormInterface
/**
* Removes the child with the given name from the form (implements the \ArrayAccess interface).
*
* @param string $name The name of the child to be removed
* @param string $name The name of the child to remove
*
* @throws AlreadyBoundException If the form has already been bound.
*/
public function offsetUnset($name)
{
@ -1043,7 +1004,7 @@ class Form implements \IteratorAggregate, FormInterface
*
* @param mixed $value The value to transform
*
* @return string
* @return mixed
*/
private function modelToNorm($value)
{
@ -1077,7 +1038,7 @@ class Form implements \IteratorAggregate, FormInterface
*
* @param mixed $value The value to transform
*
* @return string
* @return mixed
*/
private function normToView($value)
{

3
src/Symfony/Component/Form/FormBuilder.php
View File

@ -44,7 +44,8 @@ class FormBuilder extends FormConfigBuilder implements \IteratorAggregate, FormB
private $unresolvedChildren = array();
/**
* The parent of this builder
* The parent of this builder.
*
* @var FormBuilder
*/
private $parent;

18
src/Symfony/Component/Form/FormConfigBuilder.php
View File

@ -14,6 +14,7 @@ namespace Symfony\Component\Form;
use Symfony\Component\Form\Exception\FormException;
use Symfony\Component\Form\Exception\UnexpectedTypeException;
use Symfony\Component\Form\Util\PropertyPath;
use Symfony\Component\Form\Util\PropertyPathInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\EventDispatcher\ImmutableEventDispatcher;
@ -41,7 +42,7 @@ class FormConfigBuilder implements FormConfigBuilderInterface
private $name;
/**
* @var PropertyPath
* @var PropertyPathInterface
*/
private $propertyPath;
@ -143,7 +144,6 @@ class FormConfigBuilder implements FormConfigBuilderInterface
* @param EventDispatcherInterface $dispatcher The event dispatcher
* @param array $options The form options
*
* @throws UnexpectedTypeException If the name is not a string.
* @throws \InvalidArgumentException If the data class is not a valid class or if
* the name contains invalid characters.
*/
@ -244,6 +244,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3. Use
* {@link addViewTransformer()} instead.
*/
@ -263,6 +265,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3.
*/
public function prependClientTransformer(DataTransformerInterface $viewTransformer)
@ -279,6 +283,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3. Use
* {@link resetViewTransformers()} instead.
*/
@ -330,6 +336,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3.
*/
public function appendNormTransformer(DataTransformerInterface $modelTransformer)
@ -348,6 +356,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3. Use
* {@link addModelTransformer()} instead.
*/
@ -365,6 +375,8 @@ class FormConfigBuilder implements FormConfigBuilderInterface
*
* @return FormConfigBuilder The configuration object.
*
* @throws FormException if the form configuration is locked
*
* @deprecated Deprecated since version 2.1, to be removed in 2.3. Use
* {@link resetModelTransformers()} instead.
*/
@ -710,7 +722,7 @@ class FormConfigBuilder implements FormConfigBuilderInterface
throw new FormException('The config builder cannot be modified anymore.');
}
if (null !== $propertyPath && !$propertyPath instanceof PropertyPath) {
if (null !== $propertyPath && !$propertyPath instanceof PropertyPathInterface) {
$propertyPath = new PropertyPath($propertyPath);
}

8
src/Symfony/Component/Form/FormConfigBuilderInterface.php
View File

@ -162,9 +162,9 @@ interface FormConfigBuilderInterface extends FormConfigInterface
/**
* Sets the property path that the form should be mapped to.
*
* @param string|PropertyPath $propertyPath The property path or null if the path
* should be set automatically based on
* the form's name.
* @param null|string|PropertyPathInterface $propertyPath The property path or null if the path
* should be set automatically based on
* the form's name.
*
* @return self The configuration object.
*/
@ -184,7 +184,7 @@ interface FormConfigBuilderInterface extends FormConfigInterface
* Sets whether the form's data should be modified by reference.
*
* @param Boolean $byReference Whether the data should be
* modified by reference.
* modified by reference.
*
* @return self The configuration object.
*/

2
src/Symfony/Component/Form/FormConfigInterface.php
View File

@ -35,7 +35,7 @@ interface FormConfigInterface
/**
* Returns the property path that the form should be mapped to.
*
* @return Util\PropertyPath The property path.
* @return null|Util\PropertyPathInterface The property path.
*/
public function getPropertyPath();

10
src/Symfony/Component/Form/FormError.php
View File

@ -41,12 +41,12 @@ class FormError
*
* Any array key in $messageParameters will be used as a placeholder in
* $messageTemplate.
* @see Symfony\Component\Translation\Translator
* @see \Symfony\Component\Translation\Translator
*
* @param string $messageTemplate The template for the error message
* @param array $messageParameters The parameters that should be
* substituted in the message template.
* @param integer $messagePluralization The value for error message pluralization
* @param string $messageTemplate The template for the error message
* @param array $messageParameters The parameters that should be
* substituted in the message template.
* @param integer|null $messagePluralization The value for error message pluralization
*/
public function __construct($messageTemplate, array $messageParameters = array(), $messagePluralization = null)
{

36
src/Symfony/Component/Form/FormInterface.php
View File

@ -12,7 +12,7 @@
namespace Symfony\Component\Form;
/**
* A form group bundling multiple form forms
* A form group bundling multiple forms in a hierarchical structure.
*
* @author Bernhard Schussek <bschussek@gmail.com>
*/
@ -24,6 +24,10 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
* @param FormInterface $parent The parent form
*
* @return FormInterface The form instance
*
* @throws Exception\AlreadyBoundException If the form has already been bound.
* @throws Exception\FormException When trying to set a parent for a form with
* an empty name.
*/
public function setParent(FormInterface $parent = null);
@ -47,6 +51,9 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
* @param FormInterface $child The FormInterface to add as a child
*
* @return FormInterface The form instance
*
* @throws Exception\AlreadyBoundException If the form has already been bound.
* @throws Exception\FormException When trying to add a child to a non-compound form.
*/
public function add(FormInterface $child);
@ -56,6 +63,8 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
* @param string $name The name of the child
*
* @return FormInterface The child form
*
* @throws \InvalidArgumentException If the named child does not exist.
*/
public function get($name);
@ -74,6 +83,8 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
* @param string $name The name of the child to remove
*
* @return FormInterface The form instance
*
* @throws Exception\AlreadyBoundException If the form has already been bound.
*/
public function remove($name);
@ -92,11 +103,16 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
public function getErrors();
/**
* Updates the field with default data.
* Updates the form with default data.
*
* @param array $modelData The data formatted as expected for the underlying object
*
* @return FormInterface The form instance
*
* @throws Exception\AlreadyBoundException If the form has already been bound.
* @throws Exception\FormException If listeners try to call setData in a cycle. Or if
* the view data does not match the expected type
* according to {@link FormConfigInterface::getDataClass}.
*/
public function setData($modelData);
@ -111,15 +127,15 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
* Returns the normalized data of the field.
*
* @return mixed When the field is not bound, the default data is returned.
* When the field is bound, the normalized bound data is
* returned if the field is valid, null otherwise.
* When the field is bound, the normalized bound data is
* returned if the field is valid, null otherwise.
*/
public function getNormData();
/**
* Returns the data transformed by the value transformer.
*
* @return string
* @return mixed
*/
public function getViewData();
@ -154,7 +170,7 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
/**
* Returns the property path that the form is mapped to.
*
* @return Util\PropertyPath The property path.
* @return Util\PropertyPathInterface The property path.
*/
public function getPropertyPath();
@ -213,13 +229,15 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
public function isSynchronized();
/**
* Writes data into the form.
* Binds data to the form, transforms and validates it.
*
* @param mixed $data The data
* @param null|string|array $submittedData The data
*
* @return FormInterface The form instance
*
* @throws Exception\AlreadyBoundException If the form has already been bound.
*/
public function bind($data);
public function bind($submittedData);
/**
* Returns the root of the form tree.

2
src/Symfony/Component/Form/Guess/Guess.php
View File

@ -96,6 +96,8 @@ abstract class Guess
* Constructor
*
* @param integer $confidence The confidence
*
* @throws \UnexpectedValueException if the given value of confidence is unknown
*/
public function __construct($confidence)
{

2
src/Symfony/Component/Form/Util/PropertyPathBuilder.php
View File

@ -89,6 +89,8 @@ class PropertyPathBuilder
*
* @param integer $offset The offset at which to remove.
* @param integer $length The length of the removed piece.
*
* @throws \OutOfBoundsException if offset is invalid
*/
public function remove($offset, $length = 1)
{

2
src/Symfony/Component/Form/Util/PropertyPathIterator.php
View File

@ -21,7 +21,7 @@ class PropertyPathIterator extends \ArrayIterator implements PropertyPathIterato
{
/**
* The traversed property path
* @var PropertyPath
* @var PropertyPathInterface
*/
protected $path;