Generate a JSON documentation for a Svelte file
npm install sveltedoc-parserself and trusted event modifiers [Issue #80].
JSDocTypeFunction to support functions types in variable definitions and provide details about function parameters and methods.
JSDocType to support new JSDocTypeFunction.
array, object, function.
@type {import('../typings.d.ts').ExternalTypeClass}. In order to do this, new field importPath introduced to JSDocType, in the name property now it returns imported class name, f.ex.: ExternalTypeClass.
typings.d.ts file.
SvelteSlotParameter definition, to support name, description, type fields, instead of many not relevant fields that was inherited from ISvelteItem interface.
SvelteSlotItem definition, to improve consistency:
parameters property to params to be most likely the same as SvelteMethodItem. Old field still available until 5.* release.
args property renamed to params;
return item for methods:
desc property renamed to description;
type property now contains a JSDocType object instead of a string with a text representation of the type. This text representation is still available from the text property of the JSDocType object;
SvelteMethodParamItem type;
loc property removed: Use locations instead;
value property of SvelteComponentItem removed: Use importPath instead;
shell
npm install --save sveltedoc-parser
`
Features
$3
- JSDoc support
- Support description extraction for everything items
- Support visibility scope from JSDoc keywords: @public, @protected, @private
- Extract list of imported components
- Extract relative path to imported component (supports full-syntax and short-syntax import styles)
- Extract data properties
- Extract description from JSDoc comment
- Extract JS type from JSDoc (@type {string}) or parse default value if is not provided
- Extract computed properties with list of dependencies
- Extract list of references attached to components or HTML elements
- Extract information about events
- Events that propagated from child component or HTML elements
- Parse event modifiers ... on:click|once
- Extract list of used default and named slots
- Extract component methods
- Extract description from JSDoc comment
- Extract parameters description from JSDoc comment
- Extract JS type from JSDoc for parameters (@param {string} parameter)
- Identify optional parameters using brackets (@param [parameter]) or using Google ClosureCompiler syntax (@param {string=} parameter)
- Identify default values for optional parameters (@param [parameter=Default value])
- Extract source locations for component symbols
- data (props)
- slots
- methods
- refs
- events
$3
- Extract fired events
- Events fired by this component using the fire(...) method
- Custom event handlers with private visibility scope
- Extract component helpers
- Extract component actions
- Extract component transitions
$3
- Extract global component description and keywords from JSDoc comment
- Top level comment must include @component. Example script, Example html
- Extract all dispatched events
- Events that dispatched from script block by user-created dispatcher
- Events that dispatched from markup expressions by user-created dispatcher
Options
The options object passed to the parse function must include filename or fileContent.
Here are the properties supported by options (see the Usage section below):
| json Path | Description | Type | Default value |
|-----------|-------------|------|---------------|
| filename | The filename to parse. Required, unless fileContent is passed. | string |
| fileContent | The file content to parse. Required, unless filename is passed. | string |
| encoding | The file encoding. | string | utf8 |
| features | The component features to parse and extract. | string[] | All supported features |
| ignoredVisibilities | The list of ignored visibilities. Symbols with a visibility that is ignored will not be included in the output. | string[] | ['private', 'protected'] |
| includeSourceLocations | Flag, which indicates that source locations should be provided for component symbols. | boolean | false |
| version | Optional. Use 2 or 3 to specify which svelte syntax should be used. When that is not provided, parser try to detect version of the syntax. | number? | undefined |
| defaultVersion | Optional. Specify default version of svelte syntax, if auto-detector can't identify correct version. | number? | undefined |
$3
These are the values that can be included in the options.features array:
| Feature | Svelte 2 | Svelte 3 | Description |
|---------------|:--------:|:--------:|-------------------------------------------------------|
| name | ✔ | ✔ | Component's name |
| description | ✔ | ✔ | Component's description |
| keywords | ✔ | ✔ | List of JSDoc keywords found in the top level comment |
| components | ✔ | ✔ | List of imported components |
| computed | ✔ | ✔ | List of computed properties |
| data | ✔ | ✔ | List of data properties (Component's props) |
| events | ✔ | ✔ | List of events fired/dispatched by this component |
| methods | ✔ | ✔ | List of methods |
| refs | ✔ | ✔ | List of references used by this component |
| slots | ✔ | ✔ | List of slots provided by this component |
| actions | ✔ | | List of actions |
| helpers | ✔ | | List of helpers |
| transitions | ✔ | | List of transitions used by this component |
| store | | | NOT SUPPORTED |
Output format
Output format is described in this document.
For Svelte 3 examples, take a look at the examples folder to check how Svelte 3 components are transformed to JSON documents.
For a Svelte 2 example, take a look at the JSON output generated from this component.
Usage
Minimal example:
`js
const sveltedoc = require('sveltedoc-parser');
const options = {
filename: 'main.svelte'
};
sveltedoc.parse(options)
.then(componentDoc => {
console.log(componentDoc);
})
.catch(e => {
console.error(e);
});
`
or with options customization:
`js
const { parse } = require('sveltedoc-parser');
const { externalFileContent } = require('./local-file');
const options = {
fileContent: externalFileContent,
encoding: 'ascii',
features: ['data', 'computed', 'methods'],
ignoredVisibilities: ['private'],
includeSourceLocations: true,
version: 3
};
const doc = await parse(options);
console.log(doc)
`
API
$3
Method to parse svelte component and provide doc object structure with details information.
$3
Method to detect the Svelte syntax used in the component. It returns, in order:
- the value of options.version, if present; else
- 2 or 3 if Svelte 2 syntax or Svelte 3 syntax is detected, respectively; else
- the value of options.defaultVersion, if present; else
- undefined` if the function failed to detect the syntax to use