[wp-meta] [Making WordPress.org] #3920: Wrap single-quoted HTML in parameter descriptions within 'code' tags.

[Making WordPress.org]

#3920: Wrap single-quoted HTML in parameter descriptions within 'code' tags.
---------------------------+--------------------
 Reporter:  coffee2code    |      Owner:  (none)
     Type:  defect         |     Status:  new
 Priority:  normal         |  Milestone:
Component:  Developer Hub  |   Keywords:
---------------------------+--------------------
 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
 [https://core.trac.wordpress.org/ticket/38721 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 [https://developer.wordpress.org/reference/functions/comment_form/
 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.''

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/3920>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org