Make WordPress Core

Opened 12 years ago

Closed 12 years ago

#22140 closed enhancement (fixed)

fetch_feed parameter is documented incorrectly

Reported by: tlovett1's profile tlovett1 Owned by: nacin's profile 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 12 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 12 years ago.
22140.2.diff (1.5 KB) - added by JustinSainton 12 years ago.
22140.3.diff (1.3 KB) - added by JustinSainton 12 years ago.

Download all attachments as: .zip

Change History (21)

@tlovett1
12 years ago

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

#1 @tlovett1
12 years ago

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

#2 @taylorde
12 years ago

  • Cc td@… added

#3 @helenyhou
12 years ago

  • Component changed from Feeds to Inline Docs

#4 @SergeyBiryukov
12 years ago

  • Version changed from trunk to 2.8

#5 @helen
12 years ago

  • Milestone changed from Awaiting Review to 3.6

#6 @JustinSainton
12 years ago

Thinking URLs doesn't need the apostrophe here?

#7 follow-up: @SergeyBiryukov
12 years ago

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

#8 in reply to: ↑ 7 @nacin
12 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.

#9 @SergeyBiryukov
12 years ago

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

#10 @rmccue
12 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.

#11 follow-up: @nacin
12 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.

#12 @JustinSainton
12 years ago

Refreshed with nacin's suggestions.

#13 @ocean90
12 years ago

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

#14 in reply to: ↑ 11 @rmccue
12 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).

#15 @JustinSainton
12 years ago

  • Keywords dev-feedback added

#16 @SergeyBiryukov
12 years ago

  • Keywords commit added; dev-feedback removed

#17 @nacin
12 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.