Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alexprey/sveltedoc-parser
Generate a JSON documentation for a Svelte (https://github.com/sveltejs/svelte) component
https://github.com/alexprey/sveltedoc-parser
docs jsdoc parser svelte svelte-documentation sveltejs
Last synced: 25 days ago
JSON representation
Generate a JSON documentation for a Svelte (https://github.com/sveltejs/svelte) component
- Host: GitHub
- URL: https://github.com/alexprey/sveltedoc-parser
- Owner: alexprey
- License: mit
- Created: 2018-10-29T14:35:26.000Z (about 6 years ago)
- Default Branch: dev
- Last Pushed: 2023-09-02T09:17:41.000Z (about 1 year ago)
- Last Synced: 2024-10-01T15:48:42.668Z (about 1 month ago)
- Topics: docs, jsdoc, parser, svelte, svelte-documentation, sveltejs
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/sveltedoc-parser
- Size: 424 KB
- Stars: 90
- Watchers: 4
- Forks: 7
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-svelte - sveltedoc-parser - Generate a JSON documentation for your component. (Dev Tools / Docs)
README
# The sveltedoc parser
Generate a JSON documentation for a Svelte file.
[](https://www.npmjs.com/package/sveltedoc-parser)
## Table of Contents
- [Changelog](#changelog)
- [[4.2.1] 15.12.2021](#421-15122021)
- [[4.2.0] 14.12.2021](#420-14122021)
- [[4.1.0] 19.02.2021](#410-19022021)
- [[4.0.0] 25.01.2021](#400-25012021)
- [Install](#install)
- [Features](#features)
- [Common](#common)
- [Svelte 2](#svelte-2)
- [Svelte 3](#svelte-3)
- [Options](#options)
- [Supported feature names](#supported-feature-names)
- [Output format](#output-format)
- [Usage](#usage)
- [API](#api)
- [parse(options)](#parseoptions)
- [detectVersion(options)](#detectversionoptions)
- [Issues](#issues)
- [Contributors](#contributors)
- [License](#license)
## Changelog
### [4.2.1] 15.12.2021
- 🛠**[Fixed]** - Add missed dependency.
### [4.2.0] 14.12.2021
- 🔒 **[Fixed]** Upgrade all dependecies to latest version to solve known vulnarability issues.
- ✔ **[Added]** Add support ES6 default value assignment for method parameter [Issue #75](https://github.com/alexprey/sveltedoc-parser/issues/75). Thanks for [@ekhaled](https://github.com/ekhaled).
- ✔ **[Added]** Add support of method parsing when it assigned to identifier [Issue #78](https://github.com/alexprey/sveltedoc-parser/issues/78). Thanks for [@ekhaled](https://github.com/ekhaled).
- ✔ **[Added]** Extend typings to support `self` and `trusted` event modifiers [Issue #80].
- ✔ **[Added]** Introduce `JSDocTypeFunction` to support functions types in variable definitions and provide details about function parameters and methods.
- ✔ **[Added]** Extend `JSDocType` to support new `JSDocTypeFunction`.
- ✔ **[Added]** Improve type infering from assigned value. Currently support simple infering: `array`, `object`, `function`.
- 🛠**[Fixed]** Fix the [Issue #67](https://github.com/alexprey/sveltedoc-parser/issues/67), [Issue #69](https://github.com/alexprey/sveltedoc-parser/issues/69): specifier comments are not parsed properly; Thanks to [@ekhaled](https://github.com/ekhaled).
- 🛠**[Fixed]** Fix the [Issue #72](https://github.com/alexprey/sveltedoc-parser/issues/72): Module context scripts look for the wrong attribute.
- 🛠**[Fixed]** Fix the [Issue #83](https://github.com/alexprey/sveltedoc-parser/issues/83): Default value and keywords of exported aliases not merged.
### [4.1.0] 19.02.2021
- 🎉 **[Misc]** Update the ReadMe by [@soft-decay](https://github.com/soft-decay).
- ✔ **[Added]** Implement support of imported types parsing, f.ex. `@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`.
- 🛠**[Fixed]** Complete fix of [Issue #1](https://github.com/alexprey/sveltedoc-parser/issues/1): Support parsing event names from top-level constant objects with accessing to their properties by naming strings. Introduce the new issue [Issue #48](https://github.com/alexprey/sveltedoc-parser/issues/48) about supporting parse of event names by external references.
- 🛠**[Fixed]** Fix the [Issue #47](https://github.com/alexprey/sveltedoc-parser/issues/48), now all comments in markup are parsed correctly and attached to required items in document. Support JSDoc comment markup parsing in all places where comment can be used.
- 🛠**[Fixed]** Fix the [Issue #61](https://github.com/alexprey/sveltedoc-parser/issues/61), now slot parameter items enrich with all detailed information that was parsed from markup comment.
- 🛠**[Fixed]** Spec: add the module definition typings to `typings.d.ts` file.
- 🛠**[Fixed]** Fix some edge-cases in script parsing logic.
- 🛠**[Tech]** Refactor internal parser logic to make it easy to introduce new features, moves forward to TS support! ;)
- 🔥 **[Breaking]** Spec: change the `SvelteSlotParameter` definition, to support `name`, `description`, `type` fields, instead of many not relevant fields that was inherited from `ISvelteItem` interface.
- 🔥 **[Breaking]** Spec: change the `SvelteSlotItem` definition, to improve consistency:
- Rename `parameters` property to `params` to be most likely the same as `SvelteMethodItem`. Old field still available until 5.* release.
Thanks a lot [@soft-decay](https://github.com/soft-decay) for contributing in this release!
### [4.0.0] 25.01.2021
- 🛠**[Fixed]** Fix [Issue #42](https://github.com/alexprey/sveltedoc-parser/issues/42)
- 🛠**[Fixed]** Partially fixed [Issue #1](https://github.com/alexprey/sveltedoc-parser/issues/1). Event names are now correctly parsed if provided by a top-level constant in the same file. Thanks to [@soft-decay](https://github.com/soft-decay)
- ✔ **[Added]** Support complete parsing of component method arguments [Issue #39](https://github.com/alexprey/sveltedoc-parser/issues/39). Thanks to [@soft-decay](https://github.com/soft-decay)
- ✔ **[Added]** Support parsing of return type and description for methods in component [Issue #37](https://github.com/alexprey/sveltedoc-parser/issues/37). Thanks to [@soft-decay](https://github.com/soft-decay)
- ✔ **[Added]** Options validation, Thanks to [@soft-decay](https://github.com/soft-decay)
- 🔥 **[Breaking]** API rework for component methods description:
- `args` property renamed to `params`;
- Change the structure of `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;
- [Svelte2]: method arguments presented with plain array with names, now that replaced with objects of `SvelteMethodParamItem` type;
- 🔥 **[Breaking]** Cleanup deprecated code:
- `loc` property removed: Use `locations` instead;
- `value` property of `SvelteComponentItem` removed: Use `importPath` instead;
Full changelog of release versions can be found [here](/CHANGELOG.md).
## Install
```shell
npm install --save sveltedoc-parser
```
## Features
### Common
- 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
### Svelte 2
- 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
### Svelte 3
- Extract global component description and keywords from JSDoc comment
- Top level comment must include `@component`. [Example script](/test/svelte3/integration/globalComment/globalComment.script.svelte), [Example html](/test/svelte3/integration/globalComment/globalComment.markup.svelte)
- 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](#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](#Supported-feature-names) |
| **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` |
### Supported feature names
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](/typings.d.ts).
For Svelte 3 examples, take a look at the [examples folder](/examples/) to check how Svelte 3 components are transformed to JSON documents.
For a Svelte 2 example, take a look at the [JSON output](/test/svelte2/integration/overall/overall.main.doc.json) generated from [this component](/test/svelte2/integration/overall/main.svelte).
## 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
### parse(options)
Method to parse svelte component and provide doc object structure with details information.
### detectVersion(options)
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
## Issues
A list of known issues can be found [here](https://github.com/alexprey/sveltedoc-parser/issues).
Found a new issue? Please contribute and write a detailed description [here](https://github.com/alexprey/sveltedoc-parser/issues/new).
## Contributors
Author [Alexey Mulyukin](https://github.com/alexprey)
Inspired by [Vuedoc Parser](https://gitlab.com/vuedoc/parser)
## License
[MIT](/LICENSE)