Opened 6 years ago
Closed 6 years ago
#3920 closed defect (bug) (fixed)
Wrap single-quoted HTML in parameter descriptions within 'code' tags.
Reported by: | coffee2code | Owned by: | coffee2code |
---|---|---|---|
Milestone: | Priority: | normal | |
Component: | Developer Hub | Keywords: | |
Cc: |
Description
It's not easy to enforce documentation syntax formatting requirements for core. One often overlooked formatting directive is to format literal HTML examples within backticks, e.g. `<li>`
. Committers will occasionally simply put the HTML within single quotes, e.g. '<li>'
.
This most commonly occurs within parameter descriptions, for arguments that have defaults consisting of HTML tags/markup.
While this sometimes gets cleaned up during docs sweeps, those aren't very often and even then the changes wouldn't get reflected in the Code Reference until a WP release. And, as core #38721 demonstrates, pointing out such docs shortcomings can take quite a bit of time to get addressed (2 years and counting) and feedback suggests there is pushback for strict adherence to documentation formatting standards.
So, for parameter descriptions, HTML tags within single-quotes should be treated as text needing to be put within <code>
tags.
See comment_form() for an example that has multiple parameter descriptions containing single-quoted HTML.
Note: The HTML in question already gets converted to entities on display, so there isn't a concern of unintended markup being interpreted.
In 7844: