Fixed a couple of function descriptions in wp-includes/plugin.php

[amereservant]

There were a couple of errors I found in the function docblocks while tinkering in the plugins.php file as well as a confusing example, so here's what I fixed:

add_filter():
It mentioned filters were for modifying "strings", which isn't correct since you can also use filters to modify arrays, etc., so I changed the docblock to reflect this.
I also changed the example code to var_dump($example); instead of echo $example; since echoing arrays/objects etc. will cause an error.

apply_filters():
The example code block was confusing since it specified a filter function, but didn't show it being added and then just called apply_filters(), which I didn't notice the relation at first.
I added the add_filter() function in the code example for a clearer example so the reader will better understand the usage of this function.

_wp_call_all_hook():
A mysterious $hook parameter was defined in the docblock, however the parameter simply doesn't exist. Not sure if this was a passing thought or someone falling asleep while writing it, but I've removed it from the docblock.

Thanks!

[amereservant]

Patch for wp-includes/plugin.php docblocks

[SergeyBiryukov]

"it's" should probably be replaced with "their". The rest seems good.

[amereservant]

Replying to SergeyBiryukov:

"it's" should probably be replaced with "their". The rest seems good.

Agreed. The description could use a little bit of rewriting since I found the first two sentences redundant, but I didn't have the energy or the time to do it so I tried to just correct what was already written.

[nacin]

Looks fine at a glance. "it's" is wrong. It's not possessive. It should be "its".

[JustinSainton]

Just updated the possessive it's. Everything else seems good.

[SergeyBiryukov]

I still think it should be "their" (the subject is "plugins", plural).

[ericlewis]

The entire docblock here is confusing, and should be rewritten.

There is conflation of the idea "hooks" and "callbacks." A hook is either a filter or an action. Your callback function can be hooked to a hook, but the callback is not a hook.

[DrewAPicture]

19203.diff​ takes a stab at clarifying the docblocks for add_filter() and apply_filters().

[ericlewis]

attachment:19203.3.diff​ continues the effort

[nacin]

This good to go?

[DrewAPicture]

I'm good with 19203.4.diff​.

[westi]

In 25476:

Clean up the documentation for add_filter and apply_filters.

Fixes #19203 props DrewAPicture, ericlewis