# `svelte-docgen` **Inspired by [`react-docgen`](https://github.com/reactjs/react-docgen).**\ A highly customizable library that extracts information from [Svelte] components. Then returns in a structured machine-readable format from which documentation can be generated. ## Why? Because we believe in _effortless_ documentation for Svelte components. Without leaving the `*.svelte` file, which is the _source of truth_. ## Terminology - `docgen` - generated data for documentation purposes --- ## Features Our library has a focus on the following features. > [!TIP] > Is there any other feature you were looking for and you believe it should be a part of this library? > Take a look at [💡Ideas discussions](https://github.com/svelte-docgen/svelte-docgen/discussions/categories/ideas). > If it still not there, then [please 🙏 share with us!](https://github.com/svelte-docgen/svelte-docgen/discussions/new?category=ideas) ### Component description and tags It's useful to give a quick or verbose description about the Svelte component. Without leaving the original `*.svelte` file, you can provide some details to be extracted by our library. #### Description Previously, Svelte tools had a support to provide a description via HTML comment _at the root_ of the fragment. And also, it has to have a `@component` tag. Anything after this tag is treated as component _description_. **We recommend to place it at the very top of the `*.svelte` file**. Example: ```svelte ``` Our extractor handles: - multi-line, - 🚧 inlined tags, such as `{@link }` - whitespace. > [!IMPORTANT] > You are absolutely free to write component description using markdown! > > However, keep in mind that the syntax highlight is not this library responsibility. > And that this library does not parse/transform markdown syntax to HTML. #### Tags If you're familiar with JSDoc, then you already know what tags are. Every line starting with a `@` will be extracted. They can be repetitive, multi-line, contain inlined tag, etc. > [!NOTE] > They will be extracted as long as they are within the first root HTML comment with a `@component` tag. Example: ```svelte ``` > [!IMPORTANT] > > **There is no official specification for tags**, like in JSDoc or TSDoc. > This isn't our focus _yet_, and we are open to participate in this discussion. --- ### Types Our goal is to **align with terminology from TypeScript Compiler API**, which is used under the hood. This also gives the library an ability to have _computed_ types, without lies. We also hope this will help you/us to communicate and understand better what is what. Anything that will help [Svelte] ecosystem to grow and its community to strengthen its knowledge. Currently we have three categories for type kinds. #### Base types They're the _simple_ ones. > [!WARNING] > Not to be confused with primitives! They don't provide any more structure other than the name of type _kind_: - `any` - `bigint` - `boolean` - `never` - `null` - `number` - `object` - `string` - `symbol` - `undefined` - `unknown` - `void` We provide a set of types via `BASIC_TYPE_KINDS` and a type-guard function `isBaseType`. #### Structured types They're more advanced than _base_ types. Because they provide more data in their structure: - `array` - `constructible` - `function` - `interface` - `intersection` - `literal` - `tuple` - `union` We provide a set of types via `STRUCTURE_TYPE_KINDS` and a type-guard function `isStructuredType`. #### Instantiable types Well, like in TypeScript... sometimes we need to go deeper, to make types more smarter, because can be _instantiantable_. In other words, they're related to subject of using generics or generic type parameters. They have most advanced structure, so use them with caution: - `conditional` - `index` - `indexed-access` - `string-mapping` - `substitution` - `template-literal` - `type-parameter` We provide a set of types via `INSTANTIABLE_TYPE_KINDS` and a type-guard function `isInsstantiableType`. --- ### Legacy support We try to adapt to [Svelte] maintainers principle of library being backwards compatible with one major previous version - of `svelte` library. Our library is capable to recognize when the component uses a _legacy syntax_. Based on this, we provide extra information, that is related to the documentation or usage of this component. Previous major version of Svelte is `v4`, thus we extract data related to: - [slots](https://svelte.dev/docs/svelte/legacy-slots#Named-slots) - [component events](https://svelte.dev/docs/svelte/legacy-on#Component-events) > [!CAUTION] > Currently, we're unable to recognize whether slots are _optional_ or not. [Tracking issue](https://github.com/svelte-docgen/svelte-docgen/issues/10). --- ### Exports Svelte allows us to define exports inside the `*.svelte` file. Those data are important to be included in documentation. #### Modern In the modern version of Svelte, they can be defined inside the `

@svelte-docgen/extractor

Dependencies

`@svelte-docgen/extractor`