WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 2 years ago

#22140 closed enhancement (fixed)

fetch_feed parameter is documented incorrectly

Reported by: tlovett1 Owned by: nacin
Milestone: 3.6 Priority: normal
Severity: normal Version: 2.8
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

The fetch_feed function in wp-includes/feed.php is documented to allow one parameter of type string. fetch_feed passes that parameter to the set_feed_url method of a newly created SimplePie object. However, set_feed_url can accept a URL string or an array of URL's. Therefore, fetch_feed should be documented as having one parameter of mixed type (string OR array).

Attachments (4)

fetch_feed_mixed_params.diff (1.1 KB) - added by tlovett1 3 years ago.
A patch that updates the documentation for the fetch_feed method as well as renames the parameter.
22140.1.diff (1.2 KB) - added by JustinSainton 2 years ago.
22140.2.diff (1.5 KB) - added by JustinSainton 2 years ago.
22140.3.diff (1.3 KB) - added by JustinSainton 2 years ago.

Download all attachments as: .zip

Change History (21)

@tlovett13 years ago

A patch that updates the documentation for the fetch_feed method as well as renames the parameter.

comment:1 @tlovett13 years ago

  • Summary changed from fetch_feed parameter is misdocumented to fetch_feed parameter is documented incorrectly

comment:2 @taylorde2 years ago

  • Cc td@… added

comment:3 @helenyhou2 years ago

  • Component changed from Feeds to Inline Docs

comment:4 @SergeyBiryukov2 years ago

  • Version changed from trunk to 2.8

comment:5 @helen2 years ago

  • Milestone changed from Awaiting Review to 3.6

@JustinSainton2 years ago

comment:6 @JustinSainton2 years ago

Thinking URLs doesn't need the apostrophe here?

comment:7 follow-up: @SergeyBiryukov2 years ago

Not sure if we should advertise that $url can be an array here. See http://simplepie.org/wiki/faq/typical_multifeed_gotchas.

comment:8 in reply to: ↑ 7 @nacin2 years ago

Replying to SergeyBiryukov:

Not sure if we should advertise that $url can be an array here. See http://simplepie.org/wiki/faq/typical_multifeed_gotchas.

I'd be inclined to agree as well.

comment:9 @SergeyBiryukov2 years ago

  • Milestone 3.6 deleted
  • Resolution set to wontfix
  • Status changed from new to closed

comment:10 @rmccue2 years ago

-1 on wontfix. Multifeeds are used so popularly that they're basically the main way to use SimplePie.

The only real gotchas with using them are that the feed-level accessors don't make sense, since you're operating on a group rather than on a single feed. For the next version of SimplePie, I'm working on making this clearer to users, but it's fairly obvious when you try and use them anyway.

comment:11 follow-up: @nacin2 years ago

Okay, but let's tweak it a bit. Maybe something like:

@param mixed $url URL of feed to retrieve. If an array of URLs, the feeds are merged using SimplePie's multifeed feature. See also {@link http://simplepie.org/wiki/faq/typical_multifeed_gotchas}.

The "see also" is optional.

@JustinSainton2 years ago

comment:12 @JustinSainton2 years ago

Refreshed with nacin's suggestions.

comment:13 @ocean902 years ago

  • Milestone set to 3.6
  • Resolution wontfix deleted
  • Status changed from closed to reopened

comment:14 in reply to: ↑ 11 @rmccue2 years ago

Replying to nacin:

Okay, but let's tweak it a bit. Maybe something like:

@param mixed $url URL of feed to retrieve. If an array of URLs, the feeds are merged using SimplePie's multifeed feature. See also {@link http://simplepie.org/wiki/faq/typical_multifeed_gotchas}.

The "see also" is optional.

Sounds good.

Patch looks OK, but $url is used in the documentation, whereas $urls is used in the prototype. The see also has to also be on the same line (from memory).

@JustinSainton2 years ago

comment:15 @JustinSainton2 years ago

  • Keywords dev-feedback added

comment:16 @SergeyBiryukov2 years ago

  • Keywords commit added; dev-feedback removed

comment:17 @nacin2 years ago

  • Owner set to nacin
  • Resolution set to fixed
  • Status changed from reopened to closed

In 24054:

Document that fetch_feed() can accept multiple URLs, thus leveraging SimplePie's multifeed feature. props JustinSainton, fixes #22140.

Note: See TracTickets for help on using tickets.