[wp-meta] [Making WordPress.org] #2900: incorrect parsing of markdown in @param blocks

[Making WordPress.org]

#2900: incorrect parsing of markdown in @param blocks
-----------------------------+------------------
 Reporter:  pbiron           |       Owner:
     Type:  defect           |      Status:  new
 Priority:  normal           |   Milestone:
Component:  Developer Hub    |  Resolution:
 Keywords:  has-screenshots  |
-----------------------------+------------------

Comment (by pbiron):

 Sorry I wasn't more clear in the description of this ticket.

 The bug in `parsedown` only surfaces when all of the following are true:

 1. the param name contains `__` (which `parsedown` treats as the start of
 `<strong>`)
 1. the param name also occurs in the param's description (which causes
 `parsedown` to treat the occurrence of `__` in the param name as
 `</strong>`)
 1. the param name is wrapped in backticks, {{{`}}}, when it occurs in the
 param's description (because `parsedown` hasn't yet closed `</strong>`, it
 doesn't encode the opening backtick but does encode the closing backtick
 as the start of `<code>`)

 Thus, the `parsedown` bug results in "unbalanced" tags.  It's analogous to
 the the "Save as HTML/XML" bugs in old versions of MS Word, which often
 produced things like:

 {{{
 <p>this <b>is a <em>test</b> of the emergency</em> broadcast system</p>
 }}}

 when the Word document contained overlapping formatting.

 I don't think it's worth hacking the DevHub theme to get around the
 `parsedown` bug, because trying to "rebalance" overlapping tags is
 **hard** and never foolproof (plus the fix to `parsedown` is so easy).

 In case you didn't check out the PR I made against `parsedown`, you can
 temporarily fix your local copy by changing:

 {{{
 protected $StrongRegex = array(
     '*' => '/^[*]{2}((?:\\\\\*|[^*]|[*][^*]*[*])+?)[*]{2}(?![*])/s',
     '_' => '/^__((?:\\\\_|[^_]|_[^_]*_)+?)__(?!_)/us',
 );
 }}}

 to

 {{{
 protected $StrongRegex = array(
     '*' => '/^[*]{2}((?:\\\\\*|[^*]|[*][^*]*[*])+?)[*]{2}(?![*])/s',
     '_' => '/^__((?:\\\\_|[^_]|_[^_]*_)+?)__(?!_)\b/us',
 );
 }}}

 and then reslurping the source for `class-wp-term-query.php` and you'll
 see that there is no need to even touch the DevHub theme.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/2900#comment:6>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org