minor #11483 fix some docblocks (xabbuh)

fabpot · fabpot · commit abf2edf81a42 · 2014-08-02T09:53:48.000+02:00
This PR was merged into the 2.3 branch. Discussion ---------- fix some docblocks | Q | A | ------------- | --- | Bug fix? | yes | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | Commits ------- 1775da5 fix some docblocks
diff --git 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
@@ -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
@@ -287,6 +287,7 @@ protected function preNormalize($value)
      *
      * @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
@@ -884,6 +884,8 @@ protected function configureIO(InputInterface $input, OutputInterface $output)
      * @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
@@ -48,9 +48,11 @@ public function __construct()
      *
      * @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
@@ -321,7 +321,7 @@ public function askHiddenResponse(OutputInterface $output, $question, $fallback
      * @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 @@ public function askAndValidate(OutputInterface $output, $question, $validator, $
      * @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 @@ private function hasSttyAvailable()
      * @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
@@ -78,6 +78,8 @@ public function __construct()
      * @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
@@ -266,9 +266,10 @@ public function has($id)
      *
      * @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
@@ -423,7 +423,10 @@ private function addServiceProperties($id, $definition, $variableName = 'instanc
      *
      * @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 @@ private function addServices()
      *
      * @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
@@ -242,6 +242,8 @@ private function parseDefinition($id, $service, $file)
      * @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
@@ -503,6 +503,8 @@ public function setRequestHandler(RequestHandlerInterface $requestHandler)
      *
      * @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
@@ -61,6 +61,8 @@ public function __construct($file, $status = 200, $headers = array(), $public =
      * @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
@@ -286,7 +286,7 @@ public static function getMaxFilesize()
     /**
      * 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
@@ -261,8 +261,9 @@ public function preListenerCall($eventName, $eventId, $listener)
     /**
      * 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
@@ -81,6 +81,7 @@ public function setRequest(Request $request = null)
      * @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
@@ -505,7 +505,7 @@ public function parseCurrency($value, &$currency, &$position = null)
      * 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
@@ -801,12 +801,12 @@ private function updateNewFieldAceProperty($name, array $changes)
     }
 
     /**
-     * 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
@@ -61,6 +61,8 @@ public function __construct($cost)
      *
      * @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
@@ -89,6 +89,8 @@ protected function comparePasswords($password1, $password2)
     /**
      * 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
@@ -33,6 +33,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
@@ -384,6 +384,8 @@ private static function parseMapping($mapping, &$i = 0)
      * @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)
     {

Original file line number	Diff line number	Diff line change
`@@ -287,6 +287,7 @@ protected function preNormalize($value)`
`287`	`287`	`*`
`288`	`288`	`* @return mixed The finalized value`
`289`	`289`	`*`
	`290`	`+ * @throws Exception`
`290`	`291`	`* @throws InvalidConfigurationException`
`291`	`292`	`*/`
`292`	`293`	`final public function finalize($value)`
Original file line number	Diff line number	Diff line change
`@@ -884,6 +884,8 @@ protected function configureIO(InputInterface $input, OutputInterface $output)`
`884`	`884`	`* @param OutputInterface $output An Output instance`
`885`	`885`	`*`
`886`	`886`	`* @return int 0 if everything went fine, or an error code`
	`887`	`+ *`
	`888`	`+ * @throws \Exception when the command being run threw an exception`
`887`	`889`	`*/`
`888`	`890`	`protected function doRunCommand(Command $command, InputInterface $input, OutputInterface $output)`
`889`	`891`	`{`
Original file line number	Diff line number	Diff line change
`@@ -48,9 +48,11 @@ public function __construct()`
`48`	`48`	`*`
`49`	`49`	`* @param OutputInterface $output`
`50`	`50`	`* @param object $object`
`51`		`- * @param string $format`
	`51`	`+ * @param string\|null $format`
`52`	`52`	`* @param bool $raw`
`53`		`- * @param string $namespace`
	`53`	`+ * @param string\|null $namespace`
	`54`	`+ *`
	`55`	`+ * @throws \InvalidArgumentException when the given format is not supported`
`54`	`56`	`*/`
`55`	`57`	`public function describe(OutputInterface $output, $object, $format = null, $raw = false, $namespace = null)`
`56`	`58`	`{`
Original file line number	Diff line number	Diff line change
`@@ -78,6 +78,8 @@ public function __construct()`
`78`	`78`	`* @param int $layout self::LAYOUT_*`
`79`	`79`	`*`
`80`	`80`	`* @return TableHelper`
	`81`	`+ *`
	`82`	`+ * @throws InvalidArgumentException when the table layout is not known`
`81`	`83`	`*/`
`82`	`84`	`public function setLayout($layout)`
`83`	`85`	`{`
Original file line number	Diff line number	Diff line change
`@@ -266,9 +266,10 @@ public function has($id)`
`266`	`266`	`*`
`267`	`267`	`* @return object The associated service`
`268`	`268`	`*`
`269`		`- * @throws InvalidArgumentException if the service is not defined`
	`269`	`+ * @throws InvalidArgumentException if the service is not defined`
`270`	`270`	`* @throws ServiceCircularReferenceException When a circular reference is detected`
`271`		`- * @throws ServiceNotFoundException When the service is not defined`
	`271`	`+ * @throws ServiceNotFoundException When the service is not defined`
	`272`	`+ * @throws \Exception if an exception has been thrown when the service has been resolved`
`272`	`273`	`*`
`273`	`274`	`* @see Reference`
`274`	`275`	`*`
Original file line number	Diff line number	Diff line change
`@@ -423,7 +423,10 @@ private function addServiceProperties($id, $definition, $variableName = 'instanc`
`423`	`423`	`*`
`424`	`424`	`* @param string $id`
`425`	`425`	`* @param Definition $definition`
	`426`	`+ *`
`426`	`427`	`* @return string`
	`428`	`+ *`
	`429`	`+ * @throws ServiceCircularReferenceException when the container contains a circular reference`
`427`	`430`	`*/`
`428`	`431`	`private function addServiceInlinedDefinitionsSetup($id, $definition)`
`429`	`432`	`{`
`@@ -627,6 +630,8 @@ private function addServices()`
`627`	`630`	`*`
`628`	`631`	`* @param string $id A service identifier`
`629`	`632`	`* @param Definition $definition A Definition instance`
	`633`	`+ *`
	`634`	`+ * @return string\|null`
`630`	`635`	`*/`
`631`	`636`	`private function addServiceSynchronizer($id, Definition $definition)`
`632`	`637`	`{`
Original file line number	Diff line number	Diff line change
`@@ -242,6 +242,8 @@ private function parseDefinition($id, $service, $file)`
`242`	`242`	`* @param string $file`
`243`	`243`	`*`
`244`	`244`	`* @return array The file content`
	`245`	`+ *`
	`246`	`+ * @throws InvalidArgumentException when the given file is not a local file or when it does not exist`
`245`	`247`	`*/`
`246`	`248`	`protected function loadFile($file)`
`247`	`249`	`{`