Documentation fixes #528

Merged
merged 22 commits into from Dec 23, 2012

Conversation

Projects
None yet
5 participants
Contributor

BenMorel commented Dec 1, 2012

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.

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

Member

stof commented Dec 1, 2012

👍

and thanks for this work

Contributor

BenMorel commented Dec 13, 2012

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

@@ -4,7 +4,7 @@
class DbalFunctionalTestCase extends DbalTestCase
{
- /* Shared connection when a TestCase is run alone (outside of it's functional suite) */
+ /* Shared connection when a TestCase is run alone (outside of its functional suite) */
@Ocramius

Ocramius Dec 13, 2012

Owner

Should probably have @var (not really relevant though)

@BenMorel

BenMorel Dec 13, 2012

Contributor

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!

Contributor

BenMorel commented Dec 14, 2012

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 added a commit that referenced this pull request Dec 23, 2012

@beberlei beberlei merged commit e319e34 into doctrine:master Dec 23, 2012

1 check passed

default The Travis build passed
Details
Owner

beberlei commented Dec 23, 2012

Thank you for all the hard work!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment