merged branch dlsniper/docblock-enhancements (PR symfony#6383)

This PR was squashed before being merged into the master branch (closes symfony#6383). Commits ------- c2acc6c Fixed most of the docblocks/unused namespaces Discussion ---------- Fixed most of the docblocks/unused namespaces This PR fixes most/all of the docblocks in the framework. Also, this removes the unused namespaces from the sources. I've inspected the sources with the latest EAP of PhpStorm 6. Thanks! --------------------------------------------------------------------------- by dlsniper at 2012-12-16T21:03:32Z @stof let me know if I can squash the commits. Also, I've did considered about using the short class name but sometime that is not available for certain classes/contexts and it's better for IDEs to have the FQNS. --------------------------------------------------------------------------- by stof at 2012-12-16T22:32:32Z Using the short class name is a matter of coding standards. For the squashijng, I would suggest waiting the end of the work (or even letting @fabpot squash it when merging). Seeing the changes in a new commit makes it easier to review as we can see the diff between the previous review and the current state. --------------------------------------------------------------------------- by dlsniper at 2012-12-16T22:51:46Z I know about the review that's why I've asked you about squashing the commits ;) I'll commit the reminder of the needed changes asap. But on the more important part, I'll remove the long declarations where the class is already imported via ```use``` but it some cases, like https://github.com/symfony/symfony/pull/6383/files#L41R145 , I don't think it's ok not to provide IDE auto-completion just because the coding standard says so as we are using namespaces and IDEs might not be able to get it right without some small hints. What do you think? --------------------------------------------------------------------------- by dlsniper at 2012-12-16T23:14:46Z Also, look on this: ![snapshot6](https://f.cloud.github.com/assets/607868/15850/23ee18f6-47d6-11e2-8285-0c3c06a1e60d.png) As you can see, the IDE is confused about the type of the expected parameter vs returned parameter because the class isn't properly namespaced. Like I've said, humans might do ok when reading it but the tools we use to code might not so we should help them out a bit. --------------------------------------------------------------------------- by stof at 2012-12-17T09:54:04Z @dlsniper This is because the phpdoc of the ``TreeBuilder::buildTree`` is wrong. It uses the short class name but the use statement is missing --------------------------------------------------------------------------- by dlsniper at 2012-12-17T21:45:50Z That's true but I'm not sure what's the preferred fix for this. Add the missing use statement or do the FQNS which breaks the CS like you've pointed out. Any pointers? --------------------------------------------------------------------------- by mvrhov at 2012-12-18T09:37:51Z I'm adding the use statements. Beware PhpStorm will report the classes that are used only in annotations as unused! --------------------------------------------------------------------------- by stof at 2012-12-18T09:41:08Z @dlsniper there is already a bunch of places where we have use statements added for the phpdoc for return values --------------------------------------------------------------------------- by dlsniper at 2012-12-18T09:41:53Z Ok, I'll fix this issue tonight then and revert the changes. Thanks for feedback. --------------------------------------------------------------------------- by dlsniper at 2012-12-18T22:03:25Z I believe this is done. Anything that I might have missed?

Author: fabpot

src/Symfony/Bridge/Doctrine/ContainerAwareEventManager.php

@@ -93,6 +93,8 @@ public function hasListeners($event)
  *
  * @param string|array $events The event(s) to listen on.
  * @param object|string $listener The listener object.
+ *
+ * @throws \RuntimeException
  */
  public function addEventListener($events, $listener)
  {

src/Symfony/Bridge/Doctrine/DependencyInjection/AbstractDoctrineExtension.php

@@ -42,6 +42,8 @@ abstract class AbstractDoctrineExtension extends Extension
  /**
  * @param array $objectManager A configured object manager.
  * @param ContainerBuilder $container A ContainerBuilder instance
+ *
+ * @throws \InvalidArgumentException
  */
  protected function loadMappingInformation(array $objectManager, ContainerBuilder $container)
  {
@@ -119,6 +121,8 @@ protected function setMappingDriverAlias($mappingConfig, $mappingName)
  *
  * @param array $mappingConfig
  * @param string $mappingName
+ *
+ * @throws \InvalidArgumentException
  */
  protected function setMappingDriverConfig(array $mappingConfig, $mappingName)
  {
@@ -228,6 +232,8 @@ protected function registerMappingDrivers($objectManager, ContainerBuilder $cont
  *
  * @param array $mappingConfig
  * @param string $objectManagerName
+ *
+ * @throws \InvalidArgumentException
  */
  protected function assertValidMappingConfiguration(array $mappingConfig, $objectManagerName)
  {

src/Symfony/Bridge/Doctrine/DependencyInjection/CompilerPass/DoctrineValidationPass.php

@@ -47,7 +47,7 @@ public function process(ContainerBuilder $container)
  *
  * @param ContainerBuilder $container
  * @param string $mapping
- * @param type  $extension
+ * @param string $extension
  */
  private function updateValidatorMappingFiles(ContainerBuilder $container, $mapping, $extension)
  {

src/Symfony/Bridge/Doctrine/Form/ChoiceList/ORMQueryBuilderLoader.php

@@ -26,7 +26,7 @@ class ORMQueryBuilderLoader implements EntityLoaderInterface
  *
  * This property should only be accessed through queryBuilder.
  *
- * @var Doctrine\ORM\QueryBuilder
+ * @var QueryBuilder
  */
  private $queryBuilder;
 
@@ -36,6 +36,8 @@ class ORMQueryBuilderLoader implements EntityLoaderInterface
  * @param QueryBuilder|\Closure $queryBuilder
  * @param EntityManager $manager
  * @param string $class
+ *
+ * @throws UnexpectedTypeException
  */
  public function __construct($queryBuilder, $manager = null, $class = null)
  {

src/Symfony/Bridge/Doctrine/Form/DataTransformer/CollectionToArrayTransformer.php

@@ -27,6 +27,8 @@ class CollectionToArrayTransformer implements DataTransformerInterface
  * @param Collection $collection A collection of entities
  *
  * @return mixed An array of entities
+ *
+ * @throws UnexpectedTypeException
  */
  public function transform($collection)
  {

src/Symfony/Bridge/Doctrine/HttpFoundation/DbalSessionHandler.php

@@ -157,6 +157,8 @@ public function write($id, $data)
  *
  * @param string $id
  * @param string $data
+ *
+ * @return Boolean
  */
  private function createNewSession($id, $data = '')
  {

src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntityValidator.php

@@ -40,6 +40,9 @@ public function __construct(ManagerRegistry $registry)
  /**
  * @param object $entity
  * @param Constraint $constraint
+ *
+ * @throws UnexpectedTypeException
+ * @throws ConstraintDefinitionException
  */
  public function validate($entity, Constraint $constraint)
  {

src/Symfony/Bridge/Propel1/Form/ChoiceList/ModelChoiceList.php

@@ -348,6 +348,8 @@ private function load()
  *
  * @param object $model The model for which to get the identifier
  *
+ * @return array
+ *
  * @throws FormException If the model does not exist
  */
  private function getIdentifierValues($model)
@@ -367,7 +369,7 @@ private function getIdentifierValues($model)
  /**
  * Whether this column in an integer
  *
- * @param ColumnMap $column
+ * @param \ColumnMap $column
  *
  * @return Boolean
  */

src/Symfony/Bridge/Twig/Extension/HttpKernelExtension.php

@@ -51,6 +51,8 @@ public function getFunctions()
  * @param string $uri The URI to render
  *
  * @return string The Response content
+ *
+ * @throws \RuntimeException
  */
  public function render(\Twig_Environment $twig, $uri)
  {

src/Symfony/Bridge/Twig/TokenParser/TransChoiceTokenParser.php

@@ -26,6 +26,8 @@ class TransChoiceTokenParser extends TransTokenParser
  * @param \Twig_Token $token A Twig_Token instance
  *
  * @return \Twig_NodeInterface A Twig_NodeInterface instance
+ *
+ * @throws \Twig_Error_Syntax
  */
  public function parse(\Twig_Token $token)
  {