WordPress.org

Making WordPress.org

Opened 8 months ago

Closed 8 months ago

#3920 closed defect (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.

Change History (1)

#1 @coffee2code
8 months ago

  • Owner set to coffee2code
  • Resolution set to fixed
  • Status changed from new to closed

In 7844:

Developer: Wrap single-quoted HTML in parameter descriptions within 'code' tags.

Of course, HTML meant to be shown as HTML should have originally been wrapped in backticks instead of single-quotes, but fastidious adherence to documentation formatting standards isn't currently enforced.

See https://core.trac.wordpress.org/ticket/38721.
Fixes #3920.

Note: See TracTickets for help on using tickets.