WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 7 years ago

#4742 closed defect (bug) (fixed)

phpdoc for taxonomy API

Reported by: ryan Owned by:
Milestone: 2.5 Priority: normal
Severity: normal Version: 2.3
Component: Administration Keywords: taxonomy phpdoc has-patch developer-feedback
Focuses: Cc:

Description

The new taxonomy API needs phpdoc. A few of the functions in wp-includes/taxonomy.php have the beginnings of some phpdoc, but they need to be updated and extended.

Attachments (6)

taxonomy.phpdoc.diff (7.4 KB) - added by darkdragon 8 years ago.
taxonomy.phpdoc.r5900.diff (16.7 KB) - added by darkdragon 8 years ago.
Completed more phpDoc for functions. Fixed some previous descriptions, and added blank descriptions with params and return completed to other functions.
taxonomy.6159.phpdoc.patch (17.5 KB) - added by darkdragon 7 years ago.
More phpDoc for revision 6159, still incomplete.
taxonomy.6277.phpdoc.patch (28.1 KB) - added by darkdragon 7 years ago.
Added @since tags to all functions, cleaned up and correct documentation, as well as added some documentation to functions. Still Incomplete.
taxonomy.r6291.phpdoc.patch (12.1 KB) - added by darkdragon 7 years ago.
Patched against r6291 and cleans up and brings the total needing documentation to four
taxonomy.6372.phpdoc.diff (17.8 KB) - added by darkdragon 7 years ago.
Finishes documentation for the Taxonomy API, based off of r6372

Download all attachments as: .zip

Change History (24)

comment:1 @markjaquith8 years ago

Know of any good phpdoc how-to's ? It may be that a little education is what we need to accelerate phpdoc rollout.

comment:3 @josephscott8 years ago

  • Cc josephscott added

@darkdragon8 years ago

comment:4 @ryan8 years ago

(In [5896]) First cut of taxonomy API phpdoc from darkdragon. see #4742

@darkdragon8 years ago

Completed more phpDoc for functions. Fixed some previous descriptions, and added blank descriptions with params and return completed to other functions.

comment:5 @darkdragon8 years ago

Holy crap, you'll find that some functions that short and long descriptions in between others which don't. If the function was easy enough to decipher, I went ahead and filled out the information.

I figure it is easier to complete the param and return information first and then go back when the information is more clear.

Note: I place some extra non-phpdoc tags for some of the filters. Given that non-phpDoc tags won't show up and that the rest of the information is in a @internal tag, I would assume that it won't adversely affect the output. It would allow for a custom plugin or solution to take the tag (if written in PHP5 (be easier at least) ) and output all of the filter and actions information without having to do a search for add_action of add_filter functions. Just thought it might be useful.

comment:6 @Nazgul7 years ago

  • Keywords developer-feedback added

Part of this ticket was commited. Do we commit the rest for 2.3 as well or close this one and open a new ticket for 2.4?

comment:7 @ryan7 years ago

(In [6092]) More phpdoc for taxonomy from darkdragon. see #4742

comment:8 @ryan7 years ago

I applied the the second patch. Since I took so long, some parts didn't apply due to conflicts. We can keep working on phpdoc for taxonomy for 2.3 up through the RC on Sep. 17th if anyone is interested.

comment:9 @darkdragon7 years ago

Well, I do things mostly in stages. Once I realized just how many functions there were and how difficult some of the functions will be to describe I switched over to documenting the parameters, return values, and template the short description and long descriptions for later.

I think at some point, the original developer should go over what I wrote and confirm or correct what I wrote.

@darkdragon7 years ago

More phpDoc for revision 6159, still incomplete.

comment:10 @darkdragon7 years ago

Added a patch that almost completely covers the parameters and return values. Missing mostly cache functions.

This patch still doesn't completely cover the short and long descriptions for most of the functions. If anyone wants to help out with that, be my guess. I figure that at least the parameters and return types might be useful at this point of time.

comment:11 @foolswisdom7 years ago

  • Milestone changed from 2.3 to 2.4

comment:12 @ryan7 years ago

(In [6254]) More taxonomy phpdoc from darkdragon. see #4742

@darkdragon7 years ago

Added @since tags to all functions, cleaned up and correct documentation, as well as added some documentation to functions. Still Incomplete.

comment:13 @darkdragon7 years ago

Goodness, Well on the way to getting there. It always happens that I document this file whenever I'm just about ready to go to bed. I hope the documentation doesn't suffer because of it.

More this weekend I suspect.

comment:14 @ryan7 years ago

(In [6282]) taxonomy phpdoc updates from darkdragon. see #4742

@darkdragon7 years ago

Patched against r6291 and cleans up and brings the total needing documentation to four

comment:15 @darkdragon7 years ago

Dude! Only four more functions to go! Also three of them are going to be quite time consuming. Can't wait to call this file done!

Patch fixes several errors, @see should not be used in descriptions and must be on its own line.

comment:16 @foolswisdom7 years ago

Dude! Sweet!

@darkdragon7 years ago

Finishes documentation for the Taxonomy API, based off of r6372

comment:17 @darkdragon7 years ago

  • Keywords has-patch added

Patch completely documents all of the Taxonomy API.

comment:18 @ryan7 years ago

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

(In [6378]) Taxonomy phpdoc from darkdragon. fixes #4742

Note: See TracTickets for help on using tickets.