1. Contributions
  2. ›
  3. Documentation

Documentation

Below is an introduction to automated documentation features, using tools like Sveld. First we'll learn how to document component props, slots, and events. Then we'll cover how to provide this information to the documentation pages themselves.

Sveld Documentation

Components

Sveld makes use of TSDoc tags (a superset of JSDocs) to generate component documentation from the component code itself. This comes with the benefit of providing additional Intellisense features to aid developers implementing Skeleton components in tools like VS Code. Tap Ctrl/⌘ + i in a component declaration to see the extended docs come through.

Props

Sveld Reference

To document component props, simply add TSDoc description comments using the /** ... */ format. In most use cases Sveld will automatically parse all relevant information - including the prop name, type, value, and your provided description.

javascript 
/** Provide classes to set vertical item spacing. */
export let spacing: string = 'space-y-1';

For non-primitive or custom types, you may need to specify this information. This can be accomplished using the @type tag with block-style comments. Specify the type in curly brackets immediately following the tag.

javascript 
/**
 * Bind this to your form data, represents the "files" data from the input.
 * @type {FileList}
 */
export let files: FileList;

Ensure you document Context API getContext values to provide Intellisense. However, we intentionally exclude these values from the Props table.

javascript 
/** Provide classes to set the hover background color. */
export let hover: string = getContext('hover');

For additonal examples, look at existing components in the project.

Slots

Sveld Reference

Slot documentation is provided by placing a TSDoc comment block at the top (by convention) of your script block. Note that Sveld does not currently support descriptions for the default slot at this time. Instead, we recommend you opt for a Usage tab example and instructions to illustrate the use of this slot.

javascript 
// Slots
/**
 * @slot lead - Provide a leading element, such as an icon.
 * @slot content - Provide the alert message text.
 */

Events

Sveld Reference

Sveld will automatically document forwarded events. You should not attempt to document these. However, dispatched events may be documented similar to props - with a TSDocs comment applied directly above the dispatch() method. Provide the event response in curly brackets, followed by the event name, a dash, and then the event description.

javascript 
/** @event {{ event: DragEvent }} dragover - When a file is dragged over the component. */
dispatch('dragover', event);

Documentation Pages

Now that our components are ready, it's time to create the documentation page that displays all of the information derived by Sveld.

We provide a boilerplate template here:
/src/routes/(inner)/template/+page.svelte.

Copy this to the appropriate file route location and use our recommend naming convention:
e.g. /routes/components/your-new-component/+page.svelte.

Documentation Tables

To populate each documentation table we'll need to import our Sveld documentation data. Follow the instructions below:

  1. Create a duplicate of your component import statement, e.g. import Avatar from '$lib/components/Avatar/Avatar.svelte';
  2. Rename the import reference using the convention: Avatar -> sveldAvatar.
  3. Append the following URL parameters to the end of your import statement, e.g.: .../Accordion.svelte?raw&sveld.
  4. Finally, pass the import reference to the DocShell settings like so: components: [{ sveld: sveldAvatar }]

DocShell Settings

We can provide settings to our DocShell component using const settings: DocsShellSettings. This allows you to populate all relevant settings on the page.

Reference all available settings from the Typescript interface defintion.

View Available Settings

Below are existing documentation pages we recommend you reference:

  • Buttons showcases how to document Tailwind Element classes.
  • Accordion makes use of most Component settings utilizing Sveld.
  • Accordion uses Dipatched Event documentation.
  • Tooltips provides an excellent reference for Action params.

Examples

When showcasing examples of new features we typically handle this by one of two methods:

  • Sandbox (e.g. Range Sliders) - which provide a dynamic and interactive example that can be adjusted live.
  • Static (e.g. Accordion) - with multiple static examples displaying various configurations.

Dynamic examples are preferred, but remember the overall goal is to showcase how the feature operates.

Usage

In addition to examples, you should provide multiple use case demonstrations using CodeBlock snippets to help end developers understand how to make use of your new components and features.

Keyboard Interactions

Finally, don't forget to document any relevant keyboard interactions for accessibility. These can easily be provided via the DocShell settings.