Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Regression in JSDoc markdown parsing #248

Open
adidahiya opened this issue Oct 25, 2023 · 0 comments
Open

Regression in JSDoc markdown parsing #248

adidahiya opened this issue Oct 25, 2023 · 0 comments
Labels

Comments

@adidahiya
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant