WordPress.org

Make WordPress Core

Opened 9 years ago

Closed 8 years ago

#5638 closed enhancement (fixed)

PHPdoc effort for formatting.php

Reported by: darkdragon Owned by: westi
Milestone: 2.7 Priority: low
Severity: trivial Version:
Component: Optimization Keywords: phpdoc has-patch
Focuses: Cc:

Description

PHPdoc effort seeks to complete phpdoc style inline documentation for wp-includes/formatting.php.

Needed to complete:

  1. Short and Long Descriptions.
  2. @since version info
  3. parameter type and description.
  4. return type and description.

Attachments (6)

formatting.phpdoc.r6597.diff (28.8 KB) - added by darkdragon 9 years ago.
Incomplete documentation for formatting.php based off of r6597
5638.r8665.diff (18.9 KB) - added by santosj 8 years ago.
Formatting.php phpdoc fixes based off of r8665
phpdoc.formatting.diff (33.3 KB) - added by scohoust 8 years ago.
Expanded phpdoc for formatting.php
5638.r8780.diff (20.0 KB) - added by jacobsantos 8 years ago.
Corrected inline documentation (@since tags and formatting) based off of r8780
5638.r8781.diff (21.7 KB) - added by jacobsantos 8 years ago.
Just inline documentation and code styling based from r8781
5638.r8783.diff (6.1 KB) - added by jacobsantos 8 years ago.
Completes formatting.php based off of r5638.

Download all attachments as: .zip

Change History (24)

@darkdragon
9 years ago

Incomplete documentation for formatting.php based off of r6597

#1 @darkdragon
9 years ago

Looking to complete in the Summer. If anyone wants to take ownership of the file/ticket, the the patch has all of the template phpdoc style comments in order to do so.

Just apply patch to checked out revision [6597], apply patch, and then update. Finally, fill in blanks and missing information.

#2 follow-up: @scohoust
8 years ago

I've expanded a bit on what was above. I probably won't be able to spend quite so much time on this so I've added it here in case it's any use.

#3 @jacobsantos
8 years ago

Dude, awesome. The patch will have a better chance of being committed if you remove the inline documentation of the functions which don't have any short or long descriptions. However, there are other files with those messages, so it probably won't matter.

Also, formatting.php isn't the Main WordPress API, it is the WordPress Formatting API or Main WordPress Formatting API. functions.php is the main WordPress API.

#4 @scohoust
8 years ago

Quickly updated that line, must've just took it from functions.php without changing, thanks for pointing it out.

#5 @westi
8 years ago

(In [8662]) phpdoc for formatting functions. See #5638 props scohoust.

#6 in reply to: ↑ 2 @jacobsantos
8 years ago

Replying to scohoust:

I've expanded a bit on what was above. I probably won't be able to spend quite so much time on this so I've added it here in case it's any use.

That is okay man, I'll take over and complete some more functions. I'm going to correct post.php first before I jump over to formatting.php, so if you or anyone else wants to finish the file or finish some more functions that'll be sweet also.

#7 @scohoust
8 years ago

I might do a bit more this week, perhaps some of the more obvious functions, and will add anything I complete here. Thanks for committing!

@santosj
8 years ago

Formatting.php phpdoc fixes based off of r8665

#8 @santosj
8 years ago

Patch corrects some of the phpdoc, removes ending whitespace, and adds periods.

@scohoust
8 years ago

Expanded phpdoc for formatting.php

#9 @scohoust
8 years ago

Patch includes the above patch from jacobsantos plus further documentation.

#10 @westi
8 years ago

(In [8743]) phpDoc updates for formatting functions. See #5638 props scohoust and santosj.

#11 @santosj
8 years ago

@schoust

The convention has changed to where the short description doesn't have the "function_name() - " text. The reason for the change was that it doesn't make sense in PHPXref and PHPdocumentor sites as well as some editors. The reason I didn't remove all of them was I have had many conflicts in the past with the file and it helps to know which function the inline documentation goes to when conflicts do occur.

I advise that you remove them when you are finished with the inline documentation for a function to keep track of the ones that still need inline documentation. I'm submitting patches that removes them from other files.

#12 @santosj
8 years ago

Oh yeah, my patch at home has some updated descriptions and short descriptions that I'm going to make a patch for. I think some short descriptions can be improved for clarity and there are some spelling mistakes.

#13 @scohoust
8 years ago

I think I changed the "function_name() -" format from all the functions I documented. There should only be a few functions left undocumented and these are unlikely to be ones I can't explain too well.

I'm sure there are a few bits of mine that could be better written, thanks for reading it over!

@jacobsantos
8 years ago

Corrected inline documentation (@since tags and formatting) based off of r8780

#14 follow-up: @westi
8 years ago

  • Keywords reporter-feedback added
  • Owner changed from anonymous to westi
  • Status changed from new to assigned

Documentation updates look good.

Could we split the bug fixes out into a seperate ticket and just have a patch for the documentation here.

@jacobsantos
8 years ago

Just inline documentation and code styling based from r8781

#15 in reply to: ↑ 14 @jacobsantos
8 years ago

  • Keywords reporter-feedback removed

Replying to westi:

Documentation updates look good.

Could we split the bug fixes out into a seperate ticket and just have a patch for the documentation here.


Done.

#16 @westi
8 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

(In [8783]) phpDoc updates for formatting functions fixes #5638 props jacobsantos.

#17 @jacobsantos
8 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Upcoming patch completes file.

@jacobsantos
8 years ago

Completes formatting.php based off of r5638.

#18 @westi
8 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

(In [8786]) phpDoc updates for formatting functions fixes #5638 props jacobsantos.

Note: See TracTickets for help on using tickets.