Hooks Docs: wp-includes/formatting.php

[simonwheatley]

Work in progress, currently.

[simonwheatley]

Hook documentation for wp-includes/formatting.php

[simonwheatley]

Finally. :)

[kpdesign]

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

[DrewAPicture]

2nd pass

[DrewAPicture]

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.

[kpdesign]

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

no_texturize_shortcodes:

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

sanitize_file_name_chars:

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

sanitize_file_name (duplicate instance):

• Space out the filter line.

sanitize_user:

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

smilies_src:

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

is_email:

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

excerpt_length:

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

excerpt_more:

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

pre_ent2ncr:

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

richedit_pre:

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

htmledit_pre:

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

js_escape:

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

esc_html:

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

attribute_escape:

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

esc_textarea:

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

tag_escape:

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

sanitize_option_{$option}:

• @since is 2.3.0.

wp_parse_str:

• @since is 2.3.0.

wp_sprintf:

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

wp_sprintf_l:

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

sanitize_mime_type:

• @since is 3.1.3.

sanitize_trackback_urls:

• Periods after @param descriptions.

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

[DrewAPicture]

3rd pass

[DrewAPicture]

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

[DrewAPicture]

Various small tweaks

[DrewAPicture]

In 26485:

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

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

[SergeyBiryukov]

In 26486:

Correct @since values. see #25518.