Is there a standard way to document Svelte components?

Question

I come from the world of JavaDocs and love the DX of working on a thoroughly-annotated application after a certain level of complexity.

Being able to hover over and peek all the props (and implied types) of a component with some brief documentation would save me so much time instead of having to open up and read through the whole component. Better yet, running a command to generate a documentation site just like you can with JavaDocs would be dope!

Are there any standards or tools built around creating SvelteDocs? I looked through the VS Code marketplace and didn't see any documentation tooling related to Svelte.

Lucier

That would be really great if they added something. – Felicidad

Answer 1

I stumbled upon this question in search of more in-depth documentation for the hover/peek documentation method I've been using. It seems that it is not very well documented (ironically) but it is a part of Svelte language-tools and I've been using it for some time with Svelte for VS Code so I'm sure there was more documentation at some point. The way it's used is as follows in your component. I remember reading somewhere that it needs to be the first thing in your component, but I can't find that source anymore.

<!--
  @component

  some markdown here
-->

For some reasons the only documentation I can find of it is here. But it provides very nice markdown support so you can craft some very informative hover/peek documentation for your components.

EDIT:

Still can't locate official documentation for the @component commenting feature but realized it is indeed described in the FAQ: https://svelte.dev/faq#how-do-i-document-my-components Does this information belong in the actual docs? Maybe.

Disbelief

I tried this and the @component keyword adds syntax highlighting for the documentation, but it seems buggy. Also what I write doesn't appear when I hover over my component in use in another file. – Holm

Answer 2

After more digging, I found just a couple projects for documenting Svelte.

1. SvelteDoc Parser -- takes a VueDoc approach, based on JSDoc standards, generates JSON documentation for Svelte components
2. Svelte-Docs -- documentation in Markdown mixed with Svelte's features, can embed components in the generated doc pages

Both look interesting while taking completely separate approaches to solving the issue of application documentation. Perhaps there's still room to build a CLI-based site generator for the SvelteDoc Parser which could be turned into a VS Code plugin!

Lucier

Answer 3

It is difficult to find a good one. I recommend

https://github.com/carbon-design-system/sveld

It looks very promising. It offers export in Typescript definitions, JSON and Markdown. In my opinion there is only one critical bug left (Markdown generation) so hopefully it can be used very soon.

Leaseback

Answer 4

In addition to the <!-- @component commenting we've also found in VSCode ctrl+space will bring up a list of svelte component props including let: slot properties and even list their type definitions. With projects that are very much in the rough out phase we find this to be a more reliable means to get a dynamic list of available properties without having to rely on everyone remembering to update the @component comments markdown to site their added props.

In addition, any /** ... */ comments immediately preceding an exported property will display the markdown supporting comment on the property mouseover like regular jsdoc style commenting. However, we haven't found a way yet to get our slotted properties to display comments associated with their non exported variables in the script tags.

We're using the Svelte for VS Code and Svelte Intellisense plugins for VSCode.

That's about the most standardized way I've found so far though it leaves a lot for me to desire. I was really excited about Svelte-Docs and SvelteDoc Parser but it seems those projects were ditched and I haven't yet found SvelteKit documentation about bringing those into the SvelteKit fold.

Prepare

Can you make an example of the <!-- @ component doc string you include? I added the exposed propertys via @ property name but I don't get a suggestion by VS Code when hitting ctrl+space. Thanks! – Ferguson

@Ferguson the entry appears to be @ props. Also, for everyone else. . . there's spaces between the @ and the word so that this site doesn't think you're trying to notify users. – Resistant