WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

#36295 closed defect (bug) (fixed)

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

Reported by: ramiy Owned by: DrewAPicture
Milestone: 4.6 Priority: normal
Severity: normal Version:
Component: Feeds Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

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)

Attachments (3)

class-feed.php.patch (4.4 KB) - added by ramiy 4 years ago.
36295.2.diff (4.6 KB) - added by stevenkword 4 years ago.
36295.3.diff (4.9 KB) - added by stevenkword 3 years ago.

Download all attachments as: .zip

Change History (14)

#1 @ramiy
4 years ago

  • Keywords has-patch added

#2 @DrewAPicture
4 years ago

  • Milestone changed from Awaiting Review to Future Release
  • Owner set to DrewAPicture
  • Status changed from new to reviewing

#3 @stevenkword
4 years ago

  • Keywords needs-refresh added

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

#4 follow-up: @ramiy
4 years ago

@stevenkword @DrewAPicture,

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

#5 in reply to: ↑ 4 @stevenkword
4 years ago

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.

Last edited 4 years ago by stevenkword (previous) (diff)

@stevenkword
4 years ago

#6 @stevenkword
4 years ago

  • Keywords needs-refresh removed

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.

#7 @stevenkword
4 years ago

  • Milestone changed from Future Release to 4.6

#8 follow-up: @ocean90
3 years ago

  • Keywords needs-refresh added

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
3 years ago

#9 in reply to: ↑ 8 @stevenkword
3 years ago

  • Keywords needs-refresh removed

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

#10 @DrewAPicture
3 years ago

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.

#11 @DrewAPicture
3 years ago

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

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.

Note: See TracTickets for help on using tickets.