WordPress.org

Make WordPress Core

Opened 8 years ago

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

Download all attachments as: .zip

Change History (24)

@darkdragon8 years ago

Incomplete documentation for formatting.php based off of r6597

comment:1 @darkdragon8 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.

comment:2 follow-up: @scohoust7 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.

comment:3 @jacobsantos7 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.

comment:4 @scohoust7 years ago

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

comment:5 @westi7 years ago

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

comment:6 in reply to: ↑ 2 @jacobsantos7 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.

comment:7 @scohoust7 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!

@santosj7 years ago

Formatting.php phpdoc fixes based off of r8665

comment:8 @santosj7 years ago

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

@scohoust7 years ago

Expanded phpdoc for formatting.php

comment:9 @scohoust7 years ago

Patch includes the above patch from jacobsantos plus further documentation.

comment:10 @westi7 years ago

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

comment:11 @santosj7 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.

comment:12 @santosj7 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.

comment:13 @scohoust7 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!

@jacobsantos7 years ago

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

comment:14 follow-up: @westi7 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.

@jacobsantos7 years ago

Just inline documentation and code styling based from r8781

comment:15 in reply to: ↑ 14 @jacobsantos7 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.

comment:16 @westi7 years ago

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

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

comment:17 @jacobsantos7 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Upcoming patch completes file.

@jacobsantos7 years ago

Completes formatting.php based off of r5638.

comment:18 @westi7 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.