JSDoc formatter support

[arthurfiorette]

A lot of people are using JSDocs either to avoid typescript, to extend current documentation or to be read by static tools, biomejs should also format jsdoc/tsdoc comments.

For reference: https://github.com/hosseinmd/prettier-plugin-jsdoc#readme

[ematipico]

I would argue that we shouldn't provide any option, in case we wanted to provide such a feature.

[xeho91]

I found a painful point of not having this feature while documenting a library using JSDoc. 🥲
Especially when using a @example tag.

I sort of wish the DX experience would be similar to writing examples in Rust using(rustdoc) - as far I remember, rustfmt handles formatting examples as well.

/**
 * @example
 * ```
 * import { example } from "@package/example";
 * 
 * function main() {
 *     example("hello world");
 *     // Everything nested needs to be formatted manually.
 *     // If you have to copy & paste long pieces from real-life examples... 🤬
 *     // And (not 100% sure) using **spaces**, even if project has set tabs to use as identation. Otherwise syntax (using treesitter) will break - I use Neovim (LazyVim)
 * }
 * ```
 */
function example(value: string): string {
   return value;
}

[awa-xima]

Compared with e.g. JavaDoc, I understand markdown is harder to format than some HTML string. Personally, I also don't think markdown needs to much formatting, compared with HTML.

For reference, my main paint point when writing docs is having to break lines manually. For example, when I add a few word to the beginning of a longer paragraph, I then need to adjust all line breaks manually so that it fits the line length again.

/**
 * [Try adding a word to the first line -- now you need to adjust all line breaks]
 * 
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin blandit tincidunt
 * neque lobortis mattis. Integer facilisis ante nibh, tempor gravida sem porta ut.
 * Morbi non ligula nec ante iaculis fringilla ac non neque. Suspendisse sodales
 * lorem sit amet nunc facilisis, luctus tincidunt nunc varius. Phasellus eget nunc
 * risus. Donec a vulputate dolor, sed laoreet tortor. Integer tincidunt ac sem non
 * placerat. Nunc ullamcorper semper finibus. Vestibulum ut nibh interdum, 
 * sodales turpis nec, tristique dui. Mauris eu nisi et velit dictum pretium quis sit
 * amet ligula. Proin molestie neque eget mi auctor, vel accumsan mi interdum.
 * Duis placerat lectus in justo condimentum viverra. Nullam sagittis, elit id bibendum
 * aliquet, felis sapien viverra nulla, ac mattis quam dui ut ligula. Integer tempus et ipsum et cursus.
 */

[mctrafik]

I filed a ticket to add TSDoc support and it was marked as duplicate of this ticket. TSDoc != JSDoc. So that's odd. Can you update the title of this ticket to support TSDoc (https://tsdoc.org/)?!?

[ematipico]

Is TSDoc a superset of JSDoc?

Regardless, yeah, I think it makes sense to support both

[xeho91]

It sort of is. The syntax for both JSDoc and TSDoc is same, AFAIK.
Both uses "block" comments and must start with extra asterix at the start, as in /**.
There are be some differences in tag names aka (@<tag_name>).

Is also common to use markdown syntax inside those blocks. So I think this feature might have to wait until biome has a support for this language.

[mctrafik]

I'm sort of baffled that supporting something like gritql is an issue #2476 but supporting comments in typescript is still only a discussion and hasn't been promoted yet!

[atrofimov-sc]

Hi guys. Checking in here to see if we can deprecate prettier usage. Looks like this hasn't been selected for development yet. What's the blocker here? Is it markdown formatting?

[ruan-molinari]

This is what is preventing the company I work on to adopt biome. We use JSDoc to document everything, and having a formatter that works with it is essential.

[jamespsterling]

Would love to see this

[sandstrom]

Maybe biome should instead add some kind of plugin support, to avoid having to inline every single wish into main?

Would also make sense for linting rules for e.g. Vue, React, Ember, etc. Hard for a general JS linter to follow everything in these sub-communities. Plugins could also be used to add early support for TC39 stuff.

[dyc3]

See #2463. Currently we're only looking at plugins for lint rules specifically.

[sandstrom]

Great! 🙂

[mctrafik]

I think dyc3 is saying that formatter plugins will not be supported.

[sandstrom]

I'm interested in plugins for both formatting and linting, but he also said "currently", so maybe there is a chance that they'll get to formatting eventually :)