WordPress.org
Get WordPress

Make WordPress Core

Opened 7 years ago

Last modified 5 years ago

#38721 accepted defect (bug)

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

Reported by: coffee2code's profile coffee2code Owned by: drewapicture's profile 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 7 years ago.
Patch referenced in ticket.

Download all attachments as: .zip

Change History (4)

@coffee2code
7 years ago

Patch referenced in ticket.

#1 @DrewAPicture
7 years ago

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

#2 @dd32
7 years 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.

#3 @coffee2code
5 years ago

I guess it's a matter of to what degree we'd like for committers to adhere to documentation formatting standards.

For HTML tags appearing in parameter descriptions (the majority of what gets fixed by the patch), the Code Reference can treat the HTML as if it was properly originally placed within backticks. See ​meta #3821 for that.

However, for HTML appearing naked in the description of a function or hook, those get dropped during the parsing process. See ​wp_oembed_add_discovery_links() and the hook '​wp_get_custom_css' for examples where <head> should be the part of the description but is missing. I haven't investigated the parser yet to see if those tags can be escaped and retained.

Note: See TracTickets for help on using tickets.