Make WordPress Core

Opened 5 years ago

Closed 4 years ago

#17414 closed defect (bug) (fixed)

PHPDocs typos for 3.2

Reported by: duck_ Owned by: westi
Milestone: 3.2 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords:
Focuses: Cc:


For typos and such...

Attachments (4)

17414.001.diff (4.0 KB) - added by duck_ 5 years ago.
0001-Fix-four-typos-in-filesystem-.php-files-see-17414.patch (2.9 KB) - added by Utkarsh 5 years ago.
PHPDocs-typos-17414.diff (173.1 KB) - added by dremeda 5 years ago.
Typo & format fixes - No standard :/
17414.package-and-subpackage-tags.diff (51.3 KB) - added by mfields 5 years ago.
Removes @package and @subpackage from many function doc blocks. Adds these tags in a few places.

Download all attachments as: .zip

Change History (15)

5 years ago

#1 @westi
5 years ago

  • Owner set to westi
  • Status changed from new to accepted

#2 @Utkarsh
5 years ago

  • Cc admin@… added

#3 @westi
5 years ago

In [17925]:

Fix typos and inconsistencies in PHPdoc / function declarations. See #17414 props duck_

#4 @westi
5 years ago

In [17926]:

More phpdoc typo fixes. See #17414 props Utkarsh

#5 @westi
5 years ago

@Utkarsh: git formatted patches are not preferred because they require manually mangling to apply to svn checkouts.

I had to edit the patch and correct the headers to get it to apply - unless you know of an automated way :)

#6 @dremeda
5 years ago

  • Cc dre@… added

Started going through each file. There are a lot of inconsistencies. Should we be capitalizing? some comments are and others aren't, this varies within individual files and across all files. I want to make sure I'm keeping the correct format wherever possible.

Edit: Also noticed some comments are still using "Blog", is this still standard use?

Last edited 5 years ago by dremeda (previous) (diff)

5 years ago

Typo & format fixes - No standard :/

#7 @nacin
5 years ago

Wow, lots of changes. I'll have to go through those individually... Most look good, but a few general notes:

No changes to external libraries, please.

@todo is phpdoc: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.todo.pkg.html.

#8 @dremeda
5 years ago

Thanks for that Nacin. I tried to standardize wherever possible, in some cases I probably referenced the incorrect format, as the case with @todo.

If there is a better way of doing this let me know, and any other pointers are appreciated. I want to help not make things worse :)

Version 0, edited 5 years ago by dremeda (next)

#9 @mfields
5 years ago

/wp-includes/taxonomy.php appears to have a few deviations from phpDoc. Function level Doc Blocks do not support the @package or @subpackage tags. It is my understanding that functions will inherit this information from the Page Level Doc Block. Likewise methods of classes inherit this information from class-level doc blocks. I believe that many of these tags can be removed. I'd be happy to submit a patch here if this is a good idea.


5 years ago

Removes @package and @subpackage from many function doc blocks. Adds these tags in a few places.

#10 @westi
4 years ago

I don't think we should spend time on reviewing huge PHPDoc patches this close to release.

I am going to close this as fixed and would ask that you open a new 3.3-early ticket and attach the meat of these two monster patches there but broken down into smaller chunks - e.g. a folder at a time so they are easier to review and commit.

#11 @westi
4 years ago

  • Resolution set to fixed
  • Status changed from accepted to closed
Note: See TracTickets for help on using tickets.