palantir / palantir/documentalist
Regression in JSDoc markdown parsing
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 160
- Forks
- 32
- Avg merge
- 1h 40m
- Merged PRs (30d)
- 141
Description
This is a regression in v5.0.0 caused by https://github.com/palantir/documentalist/pull/156
Previously, we were easily able to include JSDoc comment markdown containing inline code snippets on interface properties.
This comment:
/**
* Props to pass to the query [InputGroup component](#core/components/input-group).
*
* Some properties are unavailable:
* - `inputProps.value`: use `query` instead
* - `inputProps.onChange`: use `onQueryChange` instead
* - `inputProps.disabled`: use `disabled` instead
* - `inputProps.fill`: use `fill` instead
*
* Other notes:
* - `inputProps.tagName` will override `popoverProps.targetTagName`
* - `inputProps.className` will work as expected, but this is redundant with the simpler `className` prop
*/
Would get parsed as the following markdown string:
'Props to pass to the [InputGroup component](#core/components/input-group).
Some properties are unavailable:
- `inputProps.value`: use `value` instead
- `inputProps.disabled`: use `disabled` instead
- `inputProps.type`: cannot be customized, always set to "text"
Note that `inputProps.tagName` will override `popoverProps.targetTagName`.'
Which would get easily rendered by marked to the following HTML:
<p>Props to pass to the query <a href="#core/components/input-group">InputGroup component</a>.</p>
<p>Some properties are unavailable:</p>
<ul>
<li><code>inputProps.value</code>: use <code>query</code> instead</li>
<li><code>inputProps.onChange</code>: use <code>onQueryChange</code> instead</li>
<li><code>inputProps.disabled</code>: use <code>disabled</code> instead</li>
<li><code>inputProps.fill</code>: use <code>fill</code> instead</li>
</ul>
<p>Other notes:</p>
<ul>
<li><code>inputProps.tagName</code> will override <code>popoverProps.targetTagName</code></li>
<li><code>inputProps.className</code> will work as expected, but this is redundant with the simpler <code>className</code> prop</li>
</ul>
Now, there's a bug where each inline code snippet gets put on its own line, which breaks markdown rendering. The JSDoc comment above gets parsed as:
`Props to pass to the [InputGroup component](#core/components/input-group).
Some properties are unavailable:
-
`inputProps.value`
: use
`value`
instead
-
`inputProps.disabled`
: use
`disabled`
instead
-
`inputProps.type`
: cannot be customized, always set to "text"
Note that
`inputProps.tagName`
will override
`popoverProps.targetTagName`
.'
Which results in this bad rendered HTML:
<p>Props to pass to the query <a href="#core/components/input-group">InputGroup component</a>.</p>
<h2>Some properties are unavailable:</h2>
<h2><code>inputProps.value</code>
: use
<code>query</code>
instead</h2>
<h2><code>inputProps.onChange</code>
: use
<code>onQueryChange</code>
instead</h2>
<h2><code>inputProps.disabled</code>
: use
<code>disabled</code>
instead</h2>
<p><code>inputProps.fill</code>
: use
<code>fill</code>
instead</p>
<h2>Other notes:</h2>
<p><code>inputProps.tagName</code>
will override
<code>popoverProps.targetTagName</code></p>
<p>-
<code>inputProps.className</code>
will work as expected, but this is redundant with the simpler
<code>className</code>
prop</p>
Which renders in Blueprint's docs like this:
This is likely a TypeDoc bug.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the TypeDoc/JSDoc markdown parsing change associated with PR #156 and compare it with the v5.0.0 regression. Done means inline code remains inline so the shown markdown renders lists and paragraphs rather than headings or broken paragraphs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100