Skip to content

Regression in JSDoc markdown parsing #248

@adidahiya

Description

@adidahiya

This is a regression in v5.0.0 caused by #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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions