[GH-528] Documentation fixes

This issue is created automatically through a Github pull request on behalf of BenMorel:

Url: https://github.com/doctrine/doctrine2/pull/528

Message:

This is a first batch of documentation fixes:

• Missing docblocks
• Missing / incorrect `@param` / `@return` / `@throws` annotations
• Missing newlines between annotations
• Incorrect vertical alignment of `@param` annotations

I'm willing to make more documentation fixes on this project, but I'll wait for your feedback on this first batch before moving forward!

Let me know if you have any comment / suggestion / question.