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: |
|
Owned by: |
|
---|---|---|---|
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 tocomment_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
ofwp_page_menu()
. - [34308] added
$submit_button
and$submit_field
as accepts$args
values 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_head
hook. - [36135] introduced the param documentation for the
$separator
option of$args
forwp_list_categories()
with an unescapted HTML default value of<br />
. - [36993] added ‘</body>’ and ‘<head>’ to @param description for
$in_footer
arg forwp_register_script()
andwp_enqueue_script()
. - [37465] introduced the
$required
hash 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$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)
Change History (4)
#2
@
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
@
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.
Patch referenced in ticket.