Fixed most of the docblocks/unused namespaces
merged branch dlsniper/docblock-enhancements (PR #6383)

This PR was squashed before being merged into the master branch (closes #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?