WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 6 years ago

#19203 closed enhancement (fixed)

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

Reported by: amereservant Owned by: westi
Milestone: 3.7 Priority: normal
Severity: normal Version: 1.5
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

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!

Attachments (6)

plugin.diff (1.9 KB) - added by amereservant 8 years ago.
Patch for wp-includes/plugin.php docblocks
19203.grammar-check.diff (1.9 KB) - added by JustinSainton 7 years ago.
19203.2.diff (1.9 KB) - added by SergeyBiryukov 7 years ago.
19203.diff (3.7 KB) - added by DrewAPicture 6 years ago.
19203.3.diff (5.5 KB) - added by ericlewis 6 years ago.
19203.4.diff (7.1 KB) - added by DrewAPicture 6 years ago.

Download all attachments as: .zip

Change History (19)

@amereservant
8 years ago

Patch for wp-includes/plugin.php docblocks

#1 follow-up: @SergeyBiryukov
8 years ago

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

#2 in reply to: ↑ 1 @amereservant
8 years ago

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.

#3 @nacin
8 years ago

  • Type changed from defect (bug) to enhancement
  • Version changed from 3.3 to 1.5

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

#4 @nacin
7 years ago

  • Keywords needs-refresh added

#5 @JustinSainton
7 years ago

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

#6 @JustinSainton
7 years ago

  • Keywords needs-refresh removed

#7 @SergeyBiryukov
7 years ago

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

#8 @ericlewis
6 years ago

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

#9 @DrewAPicture
6 years ago

  • Milestone changed from Awaiting Review to 3.7

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

@ericlewis
6 years ago

#11 @nacin
6 years ago

This good to go?

@DrewAPicture
6 years ago

#12 @DrewAPicture
6 years ago

  • Keywords commit added

I'm good with 19203.4.diff.

#13 @westi
6 years ago

  • Owner set to westi
  • Resolution set to fixed
  • Status changed from new to closed

In 25476:

Clean up the documentation for add_filter and apply_filters.

Fixes #19203 props DrewAPicture, ericlewis

Note: See TracTickets for help on using tickets.