Prettier formatting breaks JSDoc comments

[karlhorky]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Affected packages and versions

[email protected], @mdx-js/[email protected], [email protected], react@^18

Link to runnable example

No response

Steps to reproduce

1. Ensure Prettier is installed
2. Copy the example from the Props section in the readme to an MDX file
3. Format the file with Prettier
4. Observe backslashes added before asterisk characters and the error message below

   Could not parse expression with acorn MDX micromark-extension-mdx-expression:acorn
   

5. Replace the multi-line JSDoc comment with a single-line JSDoc block
6. Format the file with Prettier
7. Observe space being added before second asterisk character and error message below

   Property 'name' does not exist on type '{ readonly components?: {} | undefined; }'. ts-plugin(2339)
   

Prettier Input/Output:

Input:

{/**
  * @typedef Props
  * @property {string} name
  *   Who to greet.
  */}

{/** @typedef Props @property {string} name2 Who to greet. */}

# Hello {props.name} and {props.name2}

Output:

{/\*\*

- @typedef Props
- @property {string} name
- Who to greet.
  \*/}

{/* * @typedef Props @property {string} name2 Who to greet. */}

# Hello {props.name} and {props.name2}

Kapture.2024-07-07.at.22.17.37.mp4

Companion issue in prettier/prettier

I've also reported this as an issue in prettier/prettier:

• Extra spaces and backslashes in MDX v2+ JSDoc comments prettier/prettier#16457

If it's desired to only track it in prettier/prettier, then this issue can be closed.

Expected behavior

No problems with Prettier formatting using MDX comments with JSDoc

Actual behavior

Problems with Prettier formatting using MDX comments with JSDoc

Runtime

Node v20

Package manager

No response

OS

macOS

Build and bundle tools

No response

[ChristianMurphy]

Thanks for sharing @karlhorky!
Prettier has a number of issues with MDX 3 comments.
I'm not sure the language server can smooth those over, it probably needs to be reolved upstream, but @remcohaszing may know best.

[remcohaszing]

Duplicate of #415

[karlhorky]

Workaround

Ignore any JSDoc comments until MDX v2+ comments w. JSDoc support or MDX v3 support added:

{/* prettier-ignore-start */}

{/**
  * @typedef Props
  * @property {string} name
  *   Who to greet.
  */}

{/* prettier-ignore-end */}

# Hello {props.name}

Also added an PR to document this in the readme here:

• Add prettier-ignore-start + prettier-ignore-end workaround #455