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.

[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