Docs: Add phpdocs for WP_Feed_Cache, WP_Feed_Cache_Transient, WP_SimplePie_File, WP_SimplePie_Sanitize_KSES classes

[ramiy]

All the changes in wp-includes/class-feed.php.

The attached patch adds missing docs to classes, properties and methods.

See also: ticket #32246 (comment 325)

[stevenkword]

@ramiy

Thanks for patch. This is a good start! It looks like we still need to follow-up with some @since values and populate variable descriptions.

[ramiy]

@stevenkword @DrewAPicture,

How can I find out in which version the class/method/property was added?

[stevenkword]

Replying to ramiy:

@stevenkword @DrewAPicture,

How can I find out in which version the class/method/property was added?

@ramiy
I'm working right now on getting a process in place for this. I'll let you know my steps as soon as I get it worked out.

[stevenkword]

Hi @ramiy,

I've made a few changes through my update, (attachment:36295.2.diff​). Here are a few suggestions for upcoming patches.

• Naming your patch after the ticket it relates to will help other contributors to keep track of the many patches they see.
• When patches are submitted relative to the /src/ directory, it's a good indication that the patch author is aware of unit testing. In this document patch, it's less important, but it's good practice.
• @access values are only necessary for class methods if the class method is private. See ​PHP Documentation Standards
• @since values can be a little tricky to trace back. I checked out the entire /tags/ directory from the WordPress SVN and then used ACK to search for the first instance of a string. Something like this:

$ svn co https://core.svn.wordpress.org/tags/ core
$ cd core
$ ack -1 "class WP_SimplePie_Sanitize_KSES extends SimplePie_Sanitize"
3.5/wp-includes/class-feed.php
105:class WP_SimplePie_Sanitize_KSES extends SimplePie_Sanitize {

In this example, the class was introduced in 3.5.

[ocean90]

Looking at 36295.2.diff​: We don't use @package tags for classes, it should only be used for ​file headers. Docs should also use ​third-person singular verbs.

[stevenkword]

Replying to ocean90:

Looking at 36295.2.diff​: We don't use @package tags for classes, it should only be used for ​file headers. Docs should also use ​third-person singular verbs.

Updated in 36295.3.diff​

[DrewAPicture]

In 38056:

Docs: Add an initial @since version to wp-includes/feed.php.

The file was introduced in 2.1.0 when it was moved from wp-includes/feed-functions.php in [3862].

See #32246. See #36295.

[DrewAPicture]

In 38112:

Docs: Add missing class, method, and property DocBlocks for feed classes.

Covers:

• WP_Feed_Cache
• WP_Feed_Cache_Transient
• WP_SimplePie_File
• WP_SimplePie_Sanitize_KSES

Props ramiy, stevenkword.
Fixes #36295.