From 1775da59255010724f2864751c8d1256729727e7 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sat, 26 Jul 2014 14:09:47 +0200
Subject: [PATCH] fix some docblocks

---
 .../CompilerPass/RegisterMappingsPass.php                   | 2 +-
 .../Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php      | 3 +++
 src/Symfony/Component/Config/Definition/BaseNode.php        | 1 +
 src/Symfony/Component/Console/Application.php               | 2 ++
 src/Symfony/Component/Console/Helper/DescriptorHelper.php   | 6 ++++--
 src/Symfony/Component/Console/Helper/DialogHelper.php       | 6 +++---
 src/Symfony/Component/Console/Helper/TableHelper.php        | 2 ++
 src/Symfony/Component/DependencyInjection/Container.php     | 5 +++--
 .../Component/DependencyInjection/Dumper/PhpDumper.php      | 5 +++++
 .../Component/DependencyInjection/Loader/YamlFileLoader.php | 2 ++
 src/Symfony/Component/Form/ButtonBuilder.php                | 2 ++
 src/Symfony/Component/HttpFoundation/BinaryFileResponse.php | 2 ++
 src/Symfony/Component/HttpFoundation/File/UploadedFile.php  | 2 +-
 .../Component/HttpKernel/Debug/TraceableEventDispatcher.php | 5 +++--
 .../Component/HttpKernel/Fragment/FragmentHandler.php       | 1 +
 .../Component/Intl/NumberFormatter/NumberFormatter.php      | 2 +-
 .../Component/Security/Acl/Dbal/MutableAclProvider.php      | 6 +++---
 .../Security/Core/Encoder/BCryptPasswordEncoder.php         | 2 ++
 .../Component/Security/Core/Encoder/BasePasswordEncoder.php | 2 ++
 .../Component/Validator/Constraints/LuhnValidator.php       | 2 ++
 src/Symfony/Component/Yaml/Inline.php                       | 2 ++
 21 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/src/Symfony/Bridge/Doctrine/DependencyInjection/CompilerPass/RegisterMappingsPass.php b/src/Symfony/Bridge/Doctrine/DependencyInjection/CompilerPass/RegisterMappingsPass.php
index ac3ce490aa..e56baa1e48 100644
--- a/src/Symfony/Bridge/Doctrine/DependencyInjection/CompilerPass/RegisterMappingsPass.php
+++ b/src/Symfony/Bridge/Doctrine/DependencyInjection/CompilerPass/RegisterMappingsPass.php
@@ -74,7 +74,7 @@ abstract class RegisterMappingsPass implements CompilerPassInterface
      * @param string[]             $managerParameters list of container parameters
      *                                                that could hold the manager name
      * @param string               $driverPattern     pattern to get the metadata driver service names
-     * @param string               $enabledParameter  service container parameter that must be
+     * @param string|false         $enabledParameter  service container parameter that must be
      *                                                present to enable the mapping. Set to false
      *                                                to not do any check, optional.
      */
diff --git a/src/Symfony/Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php b/src/Symfony/Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php
index 2b04a69623..e39cc71d9e 100644
--- a/src/Symfony/Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php
+++ b/src/Symfony/Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php
@@ -80,6 +80,9 @@ class ModelChoiceList extends ObjectChoiceList
      *                                                    Either an array if $choices is given,
      *                                                    or a ModelCriteria to be merged with the $queryObject.
      * @param PropertyAccessorInterface $propertyAccessor The reflection graph for reading property paths.
+     *
+     * @throws MissingOptionsException when no model class is given
+     * @throws InvalidOptionsException when the model class cannot be found
      */
     public function __construct($class, $labelPath = null, $choices = null, $queryObject = null, $groupPath = null, $preferred = array(), PropertyAccessorInterface $propertyAccessor = null)
     {
diff --git a/src/Symfony/Component/Config/Definition/BaseNode.php b/src/Symfony/Component/Config/Definition/BaseNode.php
index 39e6d16aff..9e250c1347 100644
--- a/src/Symfony/Component/Config/Definition/BaseNode.php
+++ b/src/Symfony/Component/Config/Definition/BaseNode.php
@@ -287,6 +287,7 @@ abstract class BaseNode implements NodeInterface
      *
      * @return mixed The finalized value
      *
+     * @throws Exception
      * @throws InvalidConfigurationException
      */
     final public function finalize($value)
diff --git a/src/Symfony/Component/Console/Application.php b/src/Symfony/Component/Console/Application.php
index 88162a210e..029dc29e00 100644
--- a/src/Symfony/Component/Console/Application.php
+++ b/src/Symfony/Component/Console/Application.php
@@ -884,6 +884,8 @@ class Application
      * @param OutputInterface $output  An Output instance
      *
      * @return int 0 if everything went fine, or an error code
+     *
+     * @throws \Exception when the command being run threw an exception
      */
     protected function doRunCommand(Command $command, InputInterface $input, OutputInterface $output)
     {
diff --git a/src/Symfony/Component/Console/Helper/DescriptorHelper.php b/src/Symfony/Component/Console/Helper/DescriptorHelper.php
index 9d1a7d6144..9072efe987 100644
--- a/src/Symfony/Component/Console/Helper/DescriptorHelper.php
+++ b/src/Symfony/Component/Console/Helper/DescriptorHelper.php
@@ -48,9 +48,11 @@ class DescriptorHelper extends Helper
      *
      * @param OutputInterface $output
      * @param object          $object
-     * @param string          $format
+     * @param string|null     $format
      * @param bool            $raw
-     * @param string          $namespace
+     * @param string|null     $namespace
+     *
+     * @throws \InvalidArgumentException when the given format is not supported
      */
     public function describe(OutputInterface $output, $object, $format = null, $raw = false, $namespace = null)
     {
diff --git a/src/Symfony/Component/Console/Helper/DialogHelper.php b/src/Symfony/Component/Console/Helper/DialogHelper.php
index 57f6a6f6b4..6605e8939d 100644
--- a/src/Symfony/Component/Console/Helper/DialogHelper.php
+++ b/src/Symfony/Component/Console/Helper/DialogHelper.php
@@ -321,7 +321,7 @@ class DialogHelper extends Helper
      * @param OutputInterface $output       An Output instance
      * @param string|array    $question     The question to ask
      * @param callable        $validator    A PHP callback
-     * @param int             $attempts     Max number of times to ask before giving up (false by default, which means infinite)
+     * @param int|false       $attempts     Max number of times to ask before giving up (false by default, which means infinite)
      * @param string          $default      The default answer if none is given by the user
      * @param array           $autocomplete List of values to autocomplete
      *
@@ -350,7 +350,7 @@ class DialogHelper extends Helper
      * @param OutputInterface $output    An Output instance
      * @param string|array    $question  The question to ask
      * @param callable        $validator A PHP callback
-     * @param int             $attempts  Max number of times to ask before giving up (false by default, which means infinite)
+     * @param int|false       $attempts  Max number of times to ask before giving up (false by default, which means infinite)
      * @param bool            $fallback  In case the response can not be hidden, whether to fallback on non-hidden question or not
      *
      * @return string         The response
@@ -444,7 +444,7 @@ class DialogHelper extends Helper
      * @param callable         $interviewer  A callable that will ask for a question and return the result
      * @param OutputInterface  $output       An Output instance
      * @param callable         $validator    A PHP callback
-     * @param int              $attempts     Max number of times to ask before giving up ; false will ask infinitely
+     * @param int|false        $attempts     Max number of times to ask before giving up ; false will ask infinitely
      *
      * @return string   The validated response
      *
diff --git a/src/Symfony/Component/Console/Helper/TableHelper.php b/src/Symfony/Component/Console/Helper/TableHelper.php
index 8e4012b769..285162d4e2 100644
--- a/src/Symfony/Component/Console/Helper/TableHelper.php
+++ b/src/Symfony/Component/Console/Helper/TableHelper.php
@@ -78,6 +78,8 @@ class TableHelper extends Helper
      * @param int $layout self::LAYOUT_*
      *
      * @return TableHelper
+     *
+     * @throws InvalidArgumentException when the table layout is not known
      */
     public function setLayout($layout)
     {
diff --git a/src/Symfony/Component/DependencyInjection/Container.php b/src/Symfony/Component/DependencyInjection/Container.php
index 63b8d79a85..266aeee131 100644
--- a/src/Symfony/Component/DependencyInjection/Container.php
+++ b/src/Symfony/Component/DependencyInjection/Container.php
@@ -258,9 +258,10 @@ class Container implements IntrospectableContainerInterface
      *
      * @return object The associated service
      *
-     * @throws InvalidArgumentException if the service is not defined
+     * @throws InvalidArgumentException          if the service is not defined
      * @throws ServiceCircularReferenceException When a circular reference is detected
-     * @throws ServiceNotFoundException When the service is not defined
+     * @throws ServiceNotFoundException          When the service is not defined
+     * @throws \Exception                        if an exception has been thrown when the service has been resolved
      *
      * @see Reference
      *
diff --git a/src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php b/src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php
index 03f5f79cc1..ddcfe2a8f8 100644
--- a/src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php
+++ b/src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php
@@ -423,7 +423,10 @@ class PhpDumper extends Dumper
      *
      * @param string     $id
      * @param Definition $definition
+     *
      * @return string
+     *
+     * @throws ServiceCircularReferenceException when the container contains a circular reference
      */
     private function addServiceInlinedDefinitionsSetup($id, $definition)
     {
@@ -627,6 +630,8 @@ EOF;
      *
      * @param string     $id         A service identifier
      * @param Definition $definition A Definition instance
+     *
+     * @return string|null
      */
     private function addServiceSynchronizer($id, Definition $definition)
     {
diff --git a/src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php b/src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php
index 6f2d4c19a1..cf4cfc75bd 100644
--- a/src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php
+++ b/src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php
@@ -242,6 +242,8 @@ class YamlFileLoader extends FileLoader
      * @param string $file
      *
      * @return array The file content
+     *
+     * @throws InvalidArgumentException when the given file is not a local file or when it does not exist
      */
     protected function loadFile($file)
     {
diff --git a/src/Symfony/Component/Form/ButtonBuilder.php b/src/Symfony/Component/Form/ButtonBuilder.php
index 9302af4190..b02f8f5fe1 100644
--- a/src/Symfony/Component/Form/ButtonBuilder.php
+++ b/src/Symfony/Component/Form/ButtonBuilder.php
@@ -503,6 +503,8 @@ class ButtonBuilder implements \IteratorAggregate, FormBuilderInterface
      *
      * @param bool $initialize
      *
+     * @return ButtonBuilder
+     *
      * @throws BadMethodCallException
      */
     public function setAutoInitialize($initialize)
diff --git a/src/Symfony/Component/HttpFoundation/BinaryFileResponse.php b/src/Symfony/Component/HttpFoundation/BinaryFileResponse.php
index 55c2ac5dd6..88e2abefad 100644
--- a/src/Symfony/Component/HttpFoundation/BinaryFileResponse.php
+++ b/src/Symfony/Component/HttpFoundation/BinaryFileResponse.php
@@ -61,6 +61,8 @@ class BinaryFileResponse extends Response
      * @param null|string         $contentDisposition The type of Content-Disposition to set automatically with the filename
      * @param bool                $autoEtag           Whether the ETag header should be automatically set
      * @param bool                $autoLastModified   Whether the Last-Modified header should be automatically set
+     *
+     * @return BinaryResponse The created response
      */
     public static function create($file = null, $status = 200, $headers = array(), $public = true, $contentDisposition = null, $autoEtag = false, $autoLastModified = true)
     {
diff --git a/src/Symfony/Component/HttpFoundation/File/UploadedFile.php b/src/Symfony/Component/HttpFoundation/File/UploadedFile.php
index e9f6395201..4133d2eabc 100644
--- a/src/Symfony/Component/HttpFoundation/File/UploadedFile.php
+++ b/src/Symfony/Component/HttpFoundation/File/UploadedFile.php
@@ -286,7 +286,7 @@ class UploadedFile extends File
     /**
      * Returns an informative upload error message.
      *
-     * @param int $code The error code returned by an upload attempt
+     * @param int $errorCode The error code returned by an upload attempt
      *
      * @return string The error message regarding the specified error code
      */
diff --git a/src/Symfony/Component/HttpKernel/Debug/TraceableEventDispatcher.php b/src/Symfony/Component/HttpKernel/Debug/TraceableEventDispatcher.php
index c89978e9c4..8af3ad7c4d 100644
--- a/src/Symfony/Component/HttpKernel/Debug/TraceableEventDispatcher.php
+++ b/src/Symfony/Component/HttpKernel/Debug/TraceableEventDispatcher.php
@@ -261,8 +261,9 @@ class TraceableEventDispatcher implements EventDispatcherInterface, TraceableEve
     /**
      * Returns information about the listener
      *
-     * @param object $listener  The listener
-     * @param string $eventName The event name
+     * @param object   $listener  The listener
+     * @param int|null $eventId   The event id
+     * @param string   $eventName The event name
      *
      * @return array Information about the listener
      */
diff --git a/src/Symfony/Component/HttpKernel/Fragment/FragmentHandler.php b/src/Symfony/Component/HttpKernel/Fragment/FragmentHandler.php
index b61b0805d3..6a1654adf8 100644
--- a/src/Symfony/Component/HttpKernel/Fragment/FragmentHandler.php
+++ b/src/Symfony/Component/HttpKernel/Fragment/FragmentHandler.php
@@ -81,6 +81,7 @@ class FragmentHandler
      * @return string|null The Response content or null when the Response is streamed
      *
      * @throws \InvalidArgumentException when the renderer does not exist
+     * @throws \LogicException           when no master request is being handled
      * @throws \RuntimeException         when the Response is not successful
      */
     public function render($uri, $renderer = 'inline', array $options = array())
diff --git a/src/Symfony/Component/Intl/NumberFormatter/NumberFormatter.php b/src/Symfony/Component/Intl/NumberFormatter/NumberFormatter.php
index 563f086024..52868bb408 100644
--- a/src/Symfony/Component/Intl/NumberFormatter/NumberFormatter.php
+++ b/src/Symfony/Component/Intl/NumberFormatter/NumberFormatter.php
@@ -505,7 +505,7 @@ class NumberFormatter
      * Parse a number
      *
      * @param string $value    The value to parse
-     * @param string $type     Type of the formatting, one of the format type constants. NumberFormatter::TYPE_DOUBLE by default
+     * @param int    $type     Type of the formatting, one of the format type constants. NumberFormatter::TYPE_DOUBLE by default
      * @param int    $position Offset to begin the parsing on return this value will hold the offset at which the parsing ended
      *
      * @return bool|string                                  The parsed value of false on error
diff --git a/src/Symfony/Component/Security/Acl/Dbal/MutableAclProvider.php b/src/Symfony/Component/Security/Acl/Dbal/MutableAclProvider.php
index 42803acc07..b8f5fb8e20 100644
--- a/src/Symfony/Component/Security/Acl/Dbal/MutableAclProvider.php
+++ b/src/Symfony/Component/Security/Acl/Dbal/MutableAclProvider.php
@@ -801,12 +801,12 @@ QUERY;
     }
 
     /**
-     * This process old entries changes on an ACE related property (classFieldAces, or objectFieldAces).
+     * This processes old entries changes on an ACE related property (classFieldAces, or objectFieldAces).
      *
      * @param string $name
-     * @param array $changes
+     * @param array  $changes
      */
-    private function updateOldFieldAceProperty($ane, array $changes)
+    private function updateOldFieldAceProperty($name, array $changes)
     {
         $currentIds = array();
         foreach ($changes[1] as $field => $new) {
diff --git a/src/Symfony/Component/Security/Core/Encoder/BCryptPasswordEncoder.php b/src/Symfony/Component/Security/Core/Encoder/BCryptPasswordEncoder.php
index 1dcf3a6969..27a7334569 100644
--- a/src/Symfony/Component/Security/Core/Encoder/BCryptPasswordEncoder.php
+++ b/src/Symfony/Component/Security/Core/Encoder/BCryptPasswordEncoder.php
@@ -61,6 +61,8 @@ class BCryptPasswordEncoder extends BasePasswordEncoder
      *
      * @return string The encoded password
      *
+     * @throws BadCredentialsException when the given password is too long
+     *
      * @link http://lxr.php.net/xref/PHP_5_5/ext/standard/password.c#111
      */
     public function encodePassword($raw, $salt)
diff --git a/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php b/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php
index b27c2b0b95..5bf223bdbd 100644
--- a/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php
+++ b/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php
@@ -89,6 +89,8 @@ abstract class BasePasswordEncoder implements PasswordEncoderInterface
     /**
      * Checks if the password is too long.
      *
+     * @param string $password The password to check
+     *
      * @return bool    true if the password is too long, false otherwise
      */
     protected function isPasswordTooLong($password)
diff --git a/src/Symfony/Component/Validator/Constraints/LuhnValidator.php b/src/Symfony/Component/Validator/Constraints/LuhnValidator.php
index d3802fe99a..77e52f5040 100644
--- a/src/Symfony/Component/Validator/Constraints/LuhnValidator.php
+++ b/src/Symfony/Component/Validator/Constraints/LuhnValidator.php
@@ -32,6 +32,8 @@ class LuhnValidator extends ConstraintValidator
      *
      * @param mixed      $value
      * @param Constraint $constraint
+     *
+     * @throws UnexpectedTypeException when the given credit card number is no string
      */
     public function validate($value, Constraint $constraint)
     {
diff --git a/src/Symfony/Component/Yaml/Inline.php b/src/Symfony/Component/Yaml/Inline.php
index b0d6a031f8..0db774fcd1 100644
--- a/src/Symfony/Component/Yaml/Inline.php
+++ b/src/Symfony/Component/Yaml/Inline.php
@@ -384,6 +384,8 @@ class Inline
      * @param string $scalar
      *
      * @return string A YAML string
+     *
+     * @throws ParseException when object parsing support was disabled and the parser detected a PHP object
      */
     private static function evaluateScalar($scalar)
     {