#2900 closed defect (bug) (fixed)
incorrect parsing of markdown in @param blocks
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | Priority: | normal | |
Component: | Developer Hub | Keywords: | has-screenshots |
Cc: |
Description
There is a problem with phpdoc-parser
incorrectly parsing some markdown in DocBlocs.
For example, see the $name__like
@param in the hash of $query
in WP_Term_Query::__construct().
The problem is actually in vendor/erusev/parsedown/Parsedown.php
, rather than in phpdoc-parser
, itself.
I just submitted a Pull Request against parsedown
with a fix. If/when they accept/merge that PR, then DevHub should pull it and rebuild everything in the Code Reference.
If they don't accept/merge (or take a long time to do so), then a short term workaround is to modify the hash in all DocBlocs that use this pattern to be like:
/**
* ...
* @type string $name\__like Retrieve terms with criteria by which a term is LIKE `$name\__like.
* ...
*/
i.e., add escapes to all occurrences of __
if when it appears twice in the same @param
when the occurrence is not supposed indicate strong
.
Attachments (1)
Change History (16)
#2
@
8 years ago
We already partially handle for this case in the \DevHub\get_params()
function in the wporg-developer theme.
Doesn't make it any less of a problem, but we have already attempted to address this on DevHub. Though I notice that we're doing a str_replace()
against $tag
which is an array – should be $tag['content']
.
Anyway, the problem in this particular case isn't actually bolding, it looks like the closing </code>
tag isn't getting parsed properly from the closing backtick in the description for $name__like
, which actually causes everything below it to be <code>
formatted.
#3
@
8 years ago
Assuming we fix the $tag
vs $tag['content']
thing, there's a still a problem with an opening <code>
tag where it should be a closing </code>
tag.
Here's what the raw section description looks like coming from parsedown before wporg-developer manipulates it for display:
Retrieve terms with criteria by which a term is LIKE `$name__like<code>. Default empty. @type string $description__like
Following the fixed str_replace()
, this is what we get:
Retrieve terms with criteria by which a term is LIKE `$name</strong>like<code>. Default empty. @type string $description__like
Note the presence of the backtick before $name
and <code>
after like_
#4
@
8 years ago
After a bit more digging, I'm thinking this might have to do with the <code>
tags exception in format_param_description()
added in [2206]. Removing 'code' from the array fixes the problem for display in my minimal testing.
#5
@
8 years ago
Disregard what I said about $tag
needing to be $tag['content']
. Forgot that the subject in str_replace()
can also be an array. Either way, in the scope of DevHub, the current problem with display has to do with the open <code>
tag as described above.
#6
@
8 years ago
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:
- the param name contains
__
(whichparsedown
treats as the start of<strong>
) - the param name also occurs in the param's description (which causes
parsedown
to treat the occurrence of__
in the param name as</strong>
) - the param name is wrapped in backticks,
`
, when it occurs in the param's description (becauseparsedown
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.
This ticket was mentioned in Slack in #docs by pbiron. View the logs.
8 years ago
This ticket was mentioned in Slack in #core-docs by zzap. View the logs.
7 years ago
This ticket was mentioned in Slack in #docs by coffee2code. View the logs.
7 years ago
#11
@
7 years ago
- Owner set to coffee2code
- Resolution set to fixed
- Status changed from new to closed
In 6448:
#12
@
7 years ago
@pbiron: Thanks for your work on this, identifying the combination of criteria that triggers the bug and with submitting a PR upstream!
The commit above "fixes" the errant markup produced by the Parsedown bug. While the bug still exists upstream, I marked this ticket as fixed since there's not much else we can do on the DevHub side of things.
If you want to keep the issue alive, a ticket on the phpdoc-parser GitHub repo would seem more appropriate at this stage, to document that the bug exists, that it's a result of a bug in a dependency, and link to the PR that fixes it. With that as a reminder, someone can periodically check upstream to see if it ever gets fixed.
Cheers!
This ticket was mentioned in Slack in #meta-devhub by pbiron. View the logs.
6 years ago
#14
@
6 years ago
@coffee2code Can the same be applied to changelog entries? See https://developer.wordpress.org/reference/classes/WP_User_Query/prepare_query/#changelog for an example.
screenshot of WP_Term_Query::construct()