Documentation fixes

[BenMorel]

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.

[doctrinebot]

Hello,

thank you for positing this Pull Request. I have automatically opened an issue on our Jira Bug Tracker for you with the details of this Pull-Request. See the Link:

http://doctrine-project.org/jira/browse/DDC-2181

[stof]

👍

and thanks for this work

[BenMorel]

I'm continuing this work, please do review the changes and let me know if you have any comment!

[Ocramius]

Should probably have @var (not really relevant though)

[BenMorel]

Thanks for your comment. It is relevant actually, but I have just not processed this file yet.
I understand this can be confusing, but I've fixed the it's => its mistakes as a separate commit, that spanned the whole repository, while I work on docblocks on a file-by-file basis.
I'll continue working on the individual files, and when I'll have reviewed all the project, I'll let you know here!

[BenMorel]

I think this is pretty much done.
I've been through all the classes, with two notable exceptions:

• Doctrine\Tests\Models
• Doctrine\Tests\ORM

The first reason being that most test methods don't really need a doc (apart from @return void), the second being that it would be a massive work, that's probably not worth the investment.
That's why I preferred to focus on the core library.

I welcome all your comments on these commits, especially on @override vs @inheritdoc:

Although it's been used quite a lot in Doctrine, I couldn't find any documentation on @override in the PHPDoc documentation. The new PHPDocumentor 2 documentation does not mention an @override annotation either.
In my opinion, @override has been mostly used as a (wrong?) replacement for @inheritdoc; that's why I used @inheritdoc everywhere I saw fit.

Waiting for your feedback on all of this, guys.
I'll wait to see if you're ok to merge, and might move to DBAL and Common after that.

Cheers!

[beberlei]

Thank you for all the hard work!