[2.4] Documenting interface methods (based on entity manager)

[mvar]

This PR follows #870 and my comments on it.

I think these changes are MUST for the stable release. Especially when Doctrine is used together with such high quality framework like Symfony.

[doctrinebot]

Hello,

thank you for creating this pull request. However did not open it on the "master"
branch. Our Git workflow requires all pull requests to go through "master" branch
and the release masters then merge them back into stable branches, if they are
bug fixes.

Please open the pull request again for the "master" branch and close
this one.

Nevertheless I have opened a Jira ticket for this Pull Request to track this
issue:

http://www.doctrine-project.org/jira/browse/DDC-3409

We use Jira to track the state of pull requests and the versions they got
included in.

[mvar]

BTW, this PR won't be closed by me, because of "one exception" in contributing rules.

This undocumented interface such be treated as a bug.

[Ocramius]

@mvar any reason why this should be backported in 2.4?

[mvar]

@Ocramius the main reason is that this is needed for autocomplete as I've mentioned before. And because Doctrine 2.5 won't be released soon, this should be backported to 2.4.

Guys, you are doing great job here. Please let community to use this library with joy :)

[Ocramius]

@mvar just checked and saw that indeed the commits are the same. Merging.

[mvar]

Thank you @Ocramius