#38721 closed defect (bug) (worksforme)
Remove introduced uses of unescaped HTML from function/parameter/hook descriptions.
| Reported by: |
|
Owned by: |
|
|---|---|---|---|
| Milestone: | 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_beforeand$title_reply_afteras accepts$argsvalues tocomment_form()with default values containing HTML that is not marked as code in backticks. - [34243] added
<ul>and</ul>as defaults for$beforeand$after(respectively) to$argsofwp_page_menu(). - [34308] added
$submit_buttonand$submit_fieldas accepts$argsvalues tocomment_form()with default values containing HTML that is not marked as code in backticks. - [34903] added
<head>to function summary forwp_oembed_add_discovery_links(). - [34903] also added
<head>to the description for the newembed_headhook. - [36135] introduced the param documentation for the
$separatoroption of$argsforwp_list_categories()with an unescapted HTML default value of<br />. - [36993] added ‘</body>’ and ‘<head>’ to @param description for
$in_footerarg forwp_register_script()andwp_enqueue_script(). - [37465] introduced the
$requiredhash param towp_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$argsitems 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)
Change History (6)
#2
@
8 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
@
6 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.
#4
@
22 months ago
- Resolution set to fixed
- Status changed from accepted to closed
Closing this as fixed. The more problematic unescaped tag usages have since been fixed (mostly through rephrasing) and the instances of single-quoting of code are detected and properly formatted by the Code Reference. So there aren't any practical issues remaining other than not strictly adhering to documentation formatting standards for denoting code in inline docs (a topic which could certainly be expanded upon in the Coding Standards Handbook).
Patch referenced in ticket.