Documenting components with a docstring that appears on hover documentation

[fnune]

Problem

With React's tooling, you can comment on a component like this:

/** Documentation that will appear on hover in other places where this is imported */
function MyComponent() { return null }

However, in Svelte, I haven't found a way to do this.

Solution

I would like to know where I can place a comment that will be taken up by the on-hover documentation of editors like VSCode and Vim/Neovim (with coc.nvim).

To illustrate, here I'm hovering MyComponent but I only see import MyComponent:

I would like my docstring Documentation that will appear on hover in other places where this is imported to be included in the tooltip.

I've googled around for this for a while and tried my local setup with TypeScript and I can't find a way to do it. I found an interesting related discussion on metadata for Svelte components but the discussion is more about prop types.

Question

On the analogous issue I made on language-tools sveltejs/language-tools#280 we've been talking about HTML comments that can be picked up by svelte2tsx. However, using something like <svelte:options documentation="blabla" /> seems more idiomatic, but it would require support by the compiler.

What do you think is the best option?

[fnune]

If a proposal is accepted I would be really interested in working on it.

[dummdidumm]

My preference would be to use HTML comments for that, starting with a tag like @doc. I'm not sure if anyone would benefit from having the docs in the output which is not meant for humans to read anyway, so it seems too much overhead of adding something like this to the compiler.

The alternative would be jsdoc inside a script tag, which would feel more close to what you can do with other jsdocs, but not every svelte component has script content and adding a tag solely for the docs could feel wrong for people.

Both my comment suggestions would mean the compiler would not have to do anything and it would be purely the responsibility of the IDE tools to support that.

[fnune]

My preference would be to use HTML comments for that, starting with a tag like @doc. I'm not sure if anyone would benefit from having the docs in the output which is not meant for humans to read anyway, so it seems too much overhead of adding something like this to the compiler.

The alternative would be jsdoc inside a script tag, which would feel more close to what you can do with other jsdocs, but not every svelte component has script content and adding a tag solely for the docs could feel wrong for people.

Both my comment suggestions would mean the compiler would not have to do anything and it would be purely the responsibility of the IDE tools to support that.

I'll give implementing that a go (the HTML comment). That would be on svelte2tsx, right?

[dummdidumm]

Yes, you are welcome to do a PR at language-tools 😃

[Conduitry]

Closing, as this does indeed sound like more of a language-tools thing.

[fnune]

Fixed via sveltejs/language-tools#285 and sveltejs/language-tools#282