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.

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.

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!

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.