Skip to content

JSDoc does not strip leading * inside markdown code block #23517

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

Closed
mjbvz opened this issue Apr 18, 2018 · 3 comments · Fixed by #30939
Closed

JSDoc does not strip leading * inside markdown code block #23517

mjbvz opened this issue Apr 18, 2018 · 3 comments · Fixed by #30939
Assignees
Labels
Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Fixed A PR has been merged for this issue VS Code Priority Critical issues that VS Code needs fixed in the current TypeScript milestone

Comments

@mjbvz
Copy link
Contributor

mjbvz commented Apr 18, 2018

TypeScript Version: 2.9.0-dev.20180418

Search Terms:

  • jsdoc
  • example
  • markdown

Code

/**
 * @example
 * ```
 * 1 + 2
 * ```
*/
export function foo() { }

Hover over foo

Bug:
The jsdoc content returned includes the leading * from the comment inside the code block:

[Trace  - 11:08:38 AM] Response received: quickinfo (13). Request took 2 ms. Success: true 
Result: {
    "kind": "function",
    "kindModifiers": "export",
    "start": {
        "line": 9,
        "offset": 17
    },
    "end": {
        "line": 9,
        "offset": 20
    },
    "displayString": "function foo(): void",
    "documentation": "",
    "tags": [
        {
            "name": "example",
            "text": "```\n * 1 + 2\n * ```"
        }
]
}

This is a regression from the current 2.8 builds

@mhegazy mhegazy added Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Help Wanted You can do this labels Apr 18, 2018
@mhegazy mhegazy added this to the Community milestone Apr 18, 2018
@mhegazy
Copy link
Contributor

mhegazy commented Apr 18, 2018

PRs welcomed.

@postspectacular
Copy link

I only noticed this change in behavior now after updating VSCode, but this definitely was still working correctly a couple of months ago. Also using standard (non-fenced / non-GFM) Markdown for code blocks still works correctly now. Maybe there was a change/replacement of the MD parser?

/**
 * This works as expected (w/o leading asterisks)
 *
 * @example
 *
 *    const foo = [...mapcat((x) => [x,x,x], [1,2,3])];
 *    // [[1,1,1], [2,2,2], [3,3,3]]
 */

@JoelEinbinder
Copy link
Contributor

I bisected this one down to either b56093f or ab8233c

@mjbvz mjbvz added the VS Code Priority Critical issues that VS Code needs fixed in the current TypeScript milestone label Jan 24, 2019
weaverryan added a commit to symfony/webpack-encore that referenced this issue Apr 10, 2019
…ngs (Lyrkan)

This PR was squashed before being merged into the master branch (closes #550).

Discussion
----------

Clean up the public API file and improve a few other things

Now that we don't have many active PRs anymore I figured it was a good time to do some spring cleaning, especially in the `index.js` file (since we often recommend users to look at its content).

This PR:

* Moves the proxy creation into its own file (`lib/EncoreProxy.js`)
* Moves the content of `initializeWebpackConfig(...)` inside of the `WebpackConfig`'s constructor (we already had some checks related to the `RuntimeConfig` there anyway)
* Fixes a few JSDoc issues (missing or misplaced comments, types not resolving correctly, etc.)
* Puts examples from the `index.js` file's comments inside of Markdown code-blocks, which are supported by at least PHPStorm and VSCode:

  * In PHPStorm

  | Before | After |
  |--------|-------|
  | ![image](https://user-images.githubusercontent.com/850046/55289907-ac42bf00-53cc-11e9-9aeb-33cde4bec1f9.png) | ![image](https://user-images.githubusercontent.com/850046/55289910-b2d13680-53cc-11e9-8275-605017b2018d.png) |

  * In VSCode (note that the leading whitespaces and asterisk are caused by this bug: microsoft/TypeScript#23517)

  | Before | After |
  |--------|-------|
  | ![image](https://user-images.githubusercontent.com/850046/55289926-e4e29880-53cc-11e9-84d3-9b8a27cc33cc.png) | ![image](https://user-images.githubusercontent.com/850046/55289929-eca23d00-53cc-11e9-84cd-d8cf5082a2e9.png) |

* Indicates that `Encore.getWebpackConfig()` returns a Webpack configuration, which allows IDEs' autocompletion to work on it:

  ![image](https://user-images.githubusercontent.com/850046/55289982-aa2d3000-53cd-11e9-8abd-2c5179ec289c.png)

Commits
-------

8531000 Clean up the public API file and improve a few other things
sandersn added a commit that referenced this issue Apr 15, 2019
Previously, the jsdoc scanner had ad-hoc handling of backticks that was
similar in structure to the normal scanner's handling, but much simpler.
This was a smaller code change, but is handled backwards: the special
case of backtick-quoted parameter names was handled in the scanner
instead of in the jsdoc identifier parsing code. That made it overapply
and block correct handling of asterisks across newlines, which was most
obvious in code fences inside jsdoc, as in #23517.

Fixes #23517
@sandersn sandersn added Fixed A PR has been merged for this issue and removed Help Wanted You can do this labels Apr 15, 2019
sandersn added a commit that referenced this issue Apr 18, 2019
* Scan backticks in jsdoc as a single token less often

Previously, matching backticks in jsdoc would always be scanned as one
token to aid parsing incorrect jsdoc that uses backticks for parameter
names:

``js
/** @param {string} `nope`
 * @param {number} `not needed`
 */
```

However, this is wrong for code fences, which use triple backticks. This
fix parses a single backtick as a single token if it's immediately
followed by another backtick or by a newline. It retains the
questionable tokenisation of backticks-as-pairs in other cases, however.
A better fix might be to have the parser ignore backticks in jsdoc
instead.

* Add test case

* Handle jsdoc backticks in the parser, not scanner

Previously, the jsdoc scanner had ad-hoc handling of backticks that was
similar in structure to the normal scanner's handling, but much simpler.
This was a smaller code change, but is handled backwards: the special
case of backtick-quoted parameter names was handled in the scanner
instead of in the jsdoc identifier parsing code. That made it overapply
and block correct handling of asterisks across newlines, which was most
obvious in code fences inside jsdoc, as in #23517.

Fixes #23517

* More cleanup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Fixed A PR has been merged for this issue VS Code Priority Critical issues that VS Code needs fixed in the current TypeScript milestone
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants