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!

[SirzBenjie]

TSDoc is not a superset of JSDoc. It's quite different with its own nuances. If you do support TSDoc, please support it properly. VSCode has absolutely awful support for it.

[ematipico]

Can you expand your answer @SirzBenjie ? Please provide some resource or knowledge base, so people can study

[DayKev]

I think properly supporting JSDoc would cover 90-95% of TSDoc, though it would probably be easier to start with TSDoc since it has reference implementations to look at (cf TSDoc website).

Also VSCode's poor support isn't actually specific to TSDoc, it improperly supports JSDoc as well lol.

[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.

[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 :)

[SirzBenjie]

Formatting plugins sort of defeat the whole, you know, non-configurable formatting.

[difosfor]

I like zero config just as much as the next guy. But then Biome would need to support some conventional type of JSDoc and TSDoc formatting. It seems like a pretty essential part of the code to me. I'd still make that optional though for backwards and default Prettier compatibility.

For lack of that we could also use formatter plugin support and a plugin like prettier-plugin-jsdoc. I don't really care how.

Perhaps oxlint can provides a solution for this and other specific linting and formatting requirements with their experimental ESLint JS plugin support and eslint-plugin-jsdoc. I'm getting pretty tired of having to run eslint next to Biome to get all the rules I need.

[drdxk]

As of now this is #2 top by votes (all time) :) Would be really really nice to get there with TSDoc support, at least formatting (but tsdoc could use linting as well, since it has eslint plugins and a spec-in-progress).