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.

Edit: since we're discussing whether this is better added to the compiler, I created an analogous issue here sveltejs/svelte#5102

[dummdidumm]

Since this could also be valuable for components without a script tag, I propose using the HTML comment for that. svelte2tsx would then look for HTML comments starting with a special tag (like @doc) and put the content as a jsdoc above the default export.

Opinions? Other ideas?

[fnune]

I would be really interested in having a go at implementing this. However I think it needs to be designed carefully because it's a feature some devs use very often every day.

[fnune]

Something that comes to mind is:

/**
 * @file Here is my documentation for this component
 */

At the start of the file. But I think only HTML comments work there, right?

[fnune]

Also, maybe to make it more similar to the other tags, I feel like a <svelte:documentation> tag akin to <svelte:head> could be nice, but that would need to be implemented in the compiler.

[fnune]

Perhaps even <svelte:options documentation="blabla" />?

[jasonlyu123]

That will also needs some work in the compiler and the approval of the main repo. The options got verify by the compiler.

[fnune]

I created an analogous issue on the main repo, let's see if we can reach some conclusion 👍

[fnune]

Half of it is done once #282 gets merged. The LSP wasn't showing documentation strings on hover.

Now what I need to do is source a docstring from a @doc HTML comment and add it to addComponentExport in svelte2tsx.

[fnune]

@dummdidumm Currently it's not possible to add docstrings to the default exports, since they're not named:

export default class {
    $$prop_def = __sveltets_partial(render().props)
    $$slot_def = render().slots
}

I suppose, since the only things that can go on the root scope of each file are render and the default export, then it's harmless to give it a generic name like Component? Or maybe pick from the name of the file?

[dummdidumm]

Yes that should be no problem.

[fnune]

Does any of this code ever end up being part of the runtime of an application, or is it there just for the tooling support?