phpdoc for taxonomy API

[ryan]

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.

[markjaquith]

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

[nbachiyski]

​The kinda official one

[ryan]

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

[darkdragon]

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

[darkdragon]

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.

[Nazgul]

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?

[ryan]

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

[ryan]

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.

[darkdragon]

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.

[darkdragon]

More phpDoc for revision 6159, still incomplete.

[darkdragon]

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.

[ryan]

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

[darkdragon]

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

[darkdragon]

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.

[ryan]

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

[darkdragon]

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

[darkdragon]

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.

[foolswisdom]

Dude! Sweet!

[darkdragon]

Finishes documentation for the Taxonomy API, based off of r6372

[darkdragon]

Patch completely documents all of the Taxonomy API.

[ryan]

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