WordPress.org

Make WordPress Core

Opened 11 months ago

Last modified 10 months ago

#38721 accepted defect (bug)

Remove introduced uses of unescaped HTML from function/parameter/hook descriptions.

Reported by: coffee2code Owned by: DrewAPicture
Milestone: Awaiting Review Priority: normal
Severity: trivial Version: 4.6.1
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

#30473 culminated in [30546] for 4.1 to remove use of unescaped HTML tags (ideally referring to them by name, otherwise escaping them if they should be shown literally as an example) in function and parameter and hook descriptions. A few commits since then have introduced HTML tags that should be removed.

  • [25584] introduced documentation for the 'comment_form' action and introduced </form> in the hook description.
  • [31699] added $title_reply_before and $title_reply_after as accepts $args values to comment_form() with default values containing HTML that is not marked as code in backticks.
  • [34243] added <ul> and </ul> as defaults for $before and $after (respectively) to $args of wp_page_menu().
  • [34308] added $submit_button and $submit_field as accepts $args values to comment_form() with default values containing HTML that is not marked as code in backticks.
  • [34903] added <head> to function summary for wp_oembed_add_discovery_links().
  • [34903] also added <head> to the description for the new embed_head hook.
  • [36135] introduced the param documentation for the $separator option of $args for wp_list_categories() with an unescapted HTML default value of <br />.
  • [36993] added ‘</body>’ and ‘<head>’ to @param description for $in_footer arg for wp_register_script() and wp_enqueue_script().
  • [37465] introduced the $required hash param to wp_dropdown_categories() with <select> in the description.
  • [38829] introduced the ‘wp_get_custom_css’ filter with <head> in its description.
  • wp_list_bookmarks() has long had multiple $args items that have unescaped HTML defined as default values.

Unescaped HTML can cause (minor) display issues in many such cases for the code reference on developer.wordpress.org.

Patch attached to remove use of these unescaped HTML tags.

Related #37770.

Attachments (1)

38721.diff (9.9 KB) - added by coffee2code 11 months ago.
Patch referenced in ticket.

Download all attachments as: .zip

Change History (3)

@coffee2code
11 months ago

Patch referenced in ticket.

#1 @DrewAPicture
11 months ago

  • Owner set to DrewAPicture
  • Status changed from new to accepted

#2 @dd32
10 months ago

Would there be the option of escaping HTML automatically unless it fit into very specific situations where HTML is allowed/required/etc? (I'm unsure of where/when to use it, as i'm sure most others would be too, I always thought of it as plain-text/markdown text)

I'm wondering if manually correcting these sort of things in documentation is the best way to expend effort each release.

Note: See TracTickets for help on using tickets.