Make WordPress Core

Opened 2 years ago

Closed 23 months ago

Last modified 23 months ago

#25518 closed defect (bug) (fixed)

Hooks Docs: wp-includes/formatting.php

Reported by: simonwheatley Owned by: kpdesign
Milestone: 3.8 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:


Attachments (4)

25518.diff (20.9 KB) - added by simonwheatley 23 months ago.
Hook documentation for wp-includes/formatting.php
25518.2.diff (23.9 KB) - added by DrewAPicture 23 months ago.
2nd pass
25518.3.diff (24.0 KB) - added by DrewAPicture 23 months ago.
3rd pass
25518.4.diff (24.0 KB) - added by DrewAPicture 23 months ago.
Various small tweaks

Download all attachments as: .zip

Change History (13)

comment:1 @DrewAPicture2 years ago

  • Component changed from General to Inline Docs
  • Keywords needs-patch added

comment:2 @simonwheatley2 years ago

Work in progress, currently.

@simonwheatley23 months ago

Hook documentation for wp-includes/formatting.php

comment:3 @simonwheatley23 months ago

  • Keywords has-patch added; needs-patch removed

Finally. :)

comment:4 @kpdesign23 months ago

Thank you. :) We'll review the patch, and get back with you on any changes.

@DrewAPicture23 months ago

2nd pass

comment:5 @DrewAPicture23 months ago

  • Owner set to kpdesign
  • Status changed from new to reviewing

25518.2.diff is a comprehensive second pass on 25518.diff.

Notable changes:

  • @since versions converted to 3-digit x.x.x style
  • Most of the short descriptions were rewritten to reflect was is actually filterable
  • Fixed duplicate filter notations
  • Minimized changed code wherever possible, except for spacing out apply_filters lines.

This should be ready to go after a secondary review.

comment:6 @kpdesign23 months ago

  • Keywords needs-patch added; has-patch removed

@DrewAPicture: Thanks for the changes in 25518.2.diff. There's just a few tweaks to be made:


  • s/texturise/texturize in both the short description and $var name in @param.
  • Var in @param should be $default_no_texturize_shortcodes.


  • Align the $vars and descriptions in the @param lines.

sanitize_file_name (duplicate instance):

  • Space out the filter line.


  • Align the $vars and descriptions in the @param lines.


  • Short description: "Filter the Smiley image URL before being used in the image element." We've been spelling out the element name in other places, so 'image' for consistency.


  • s/such as 'email_to_short'/such as 'email_too_short' in long description.
  • @param $is_email short description: "Whether the email address has passed the is_email() checks. Default false."


  • Short description should be "Filter the number of words in an excerpt."
  • @param description should be "The number of words. Default '55'."


  • Short description: "Filter the string in the more link displayed after a trimmed excerpt."
  • Remove extra whitespace at end of @param line.


  • Align the $vars and descriptions in the @param lines.


  • Long description alternative (to avoid inline html tags):

"This filter is first evaluated, and the value returned, if an empty string is passed to wp_richedit_pre(). If an empty string is passed, it results in a break tag and line feed. If a non-empty string is passed, the filter is evaluated on the wp_richedit_pre() return after being formatted."


  • Short description: "Filter the text before it is formatted for the HTML editor."
  • @since should be 2.5.0 (3-digit).


  • @since is 2.0.11.
  • Remove extra whitespace at end of blank line below @since.


  • @since is 2.8.0.
  • Remove extra whitespace at end of blank line below @since.


  • @since is 2.0.11.
  • Remove extra whitespace at end of blank line below @since.


  • Remove extra whitespace at end of blank line below @since.


  • Short description for $safe_tag - s/it's/it has.
  • Remove extra whitespace at end of blank line below @since.


  • @since is 2.3.0.


  • @since is 2.3.0.


  • Long description: "If the fragment is unchanged, then" (add a comma after unchanged).


  • I think we should move the comment above the block into a long description for the filter.


  • @since is 3.1.3.


  • Periods after @param descriptions.

Could you incorporate these changes and submit a new patch please? :)

@DrewAPicture23 months ago

3rd pass

comment:7 @DrewAPicture23 months ago

  • Keywords has-patch commit added; needs-patch removed
  • Milestone changed from Awaiting Review to 3.8

25518.3.diff applies the suggested changes from comment:6.

@DrewAPicture23 months ago

Various small tweaks

comment:8 @DrewAPicture23 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 26485:

Inline documentation for hooks in wp-includes/formatting.php.

Props simonwheatley for the initial patch. Props DrewAPicture, kpdesign.
Fixes #25518.

comment:9 @SergeyBiryukov23 months ago

In 26486:

Correct @since values. see #25518.

Note: See TracTickets for help on using tickets.