palantir / palantir/documentalist

Regression in JSDoc markdown parsing

Open
#248 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
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:

image

This is likely a TypeDoc bug.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.