PHPdoc effort for formatting.php

[darkdragon]

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.

[darkdragon]

Incomplete documentation for formatting.php based off of r6597

[darkdragon]

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.

[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.

[jacobsantos]

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.

[scohoust]

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

[westi]

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

[jacobsantos]

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.

[scohoust]

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]

Formatting.php phpdoc fixes based off of r8665

[santosj]

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

[scohoust]

Expanded phpdoc for formatting.php

[scohoust]

Patch includes the above patch from jacobsantos plus further documentation.

[westi]

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

[santosj]

@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.

[santosj]

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.

[scohoust]

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]

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

[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.

[jacobsantos]

Just inline documentation and code styling based from r8781

[jacobsantos]

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.

[westi]

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

[jacobsantos]

Upcoming patch completes file.

[jacobsantos]

Completes formatting.php based off of r5638.

[westi]

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