hosseinmd / prettier-plugin-jsdoc

A Prettier plugin to format JSDoc comments.
MIT License
228 stars 29 forks source link

Horizontal rules are removed (`---`, `___` and `***`; i.e. `<hr />`) #216

Open Deckstar opened 11 months ago

Deckstar commented 11 months ago

Hello! 😄 Great library! I'm loving it! 🙂

My only complaint is that it seems to remove break-lines (also known as horizontal rules).

Here's what I mean. Consider this case:

Input:

export interface Props {
  /**
   * The target element.
   *
   * ---
   * 
   * Some more notes here.
   * 
   * @default window
   */
  target?: Node | Window;
}

Expected:

// ... unchanged

Actual result:

export interface Props {
  /**
   * The target element.
   *
   * Some more notes here.
   *
   * @default window
   */
  target?: Node | Window;
}

The result is almost the same, except that the --- characters have been removed!

I can confirm that this occurs in both TypeScript and JavaScript files, with both types (e.g. interfaces) and runtime code (e.g. functions).

The same occurs if I try to use *** or ___ — the line gets removed.


I've tried a variety of things to try to get the lines to stay, but they always seem to be removed no matter what.

This is a bit of a bummer, as I really like to use those to separate the "main" documentation from other notes, like params descriptions or defaults, or "read more" / "source" kinds of notes. I see no reason why these should be removed. They are perfectly valid syntax, and don't break any best practices, right?

Were it not for this issue, I would implement this library in all my code bases ASAP 😄

Hopefully this is fixable? 🙂 Maybe it should be a config option?

Thank you!

irahopkinson commented 10 months ago

Work-around: I just used a ~-~ as a divider and that was retained, however although that gives the space it doesn't show as a divider.

hosseinmd commented 10 months ago

Add for space before dash like:

export interface Props {
  /**
   * The target element.
   *
   *     ---
   * 
   * Some more notes here.
   * 
   * @default window
   */
  target?: Node | Window;
}
irahopkinson commented 10 months ago

Adding the 5 spaces after the * and before the --- does allow it to be retained, however it still doesn't show as a JSDoc divider. Please re-open this issue.

hosseinmd commented 10 months ago

I don't remember where it comes from.