fetch_feed parameter is documented incorrectly

[tlovett1]

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

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

Thinking URLs doesn't need the apostrophe here?

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

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.

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

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.

Refreshed with nacin's suggestions.

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

In 24054:

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