Generate a JSON documentation for a Vue file
Generate a JSON documentation for a Vue file component.
- Install
- Features
- Options
- Programmatic usage
- Command line options
- Command line usage
- Syntax
* Add component name
* Add component description
* Annotate props
+ Annotate a v-model prop
+ Annotate Vue Array String Props
+ Special tags for props
+ Prop Entry Interface
* Annotate data
* Annotate computed properties
* Annotate methods
* Annotate events
* Annotate slots
* Ignore items from parsing
- Tags Extraction
- Supported Tags
- Working with Mixins
- Parsing control with options.features
- Using Plugins
* Adding a Plugin
* Official Plugins
* Building Plugins
- Language Processing
* Loader API
* Built-in loaders
* Create a custom loader
- Parsing Output Interface
- Generate Markdown Documentation
- Contribute
- Versioning
- License
This package is ESM only
: Node 16+ is needed to use it and it must be imported instead of required.
``sh`
npm install --save @vuedoc/parser
- Extract the component name (from the name field or from the filename)model
- Extract the component description
- Keywords support
- Extract component , props, data, computed properties,events
, slots and methods
- Vue 3 support with Composition API
- JSX support
- Class Component support
- Vue Property Decorator support
- Prop Types support
- JSDoc support
(,@param
,@returns
,@version
,@since
,@deprecated
,@see
,@kind
,@author
and@ignore
tags)@param
- TypeDoc tags
support (, @return(s), @hidden, @category)
| Name | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filename | The filename to parse. Required unless filecontent is passed |filecontent
| | The file content to parse. Required unless filename is passed |encoding
| | The file encoding. Default is 'utf8' |features
| | The component features to parse and extract.['name', 'description', 'slots', 'props', 'data', 'computed', 'events', 'methods']
Default features: |loaders
| | Use this option to define custom loaders for specific languages |ignoredVisibilities
| | List of ignored visibilities. Default: ['protected', 'private'] |composition
| | Additional composition tokens for advanced components.{ data: [], methods: [], computed: [], props: [] }
Default value: |resolver
| | A resolver object used to resolve imports statements. See definition file types/ImportResolver.d.ts |plugins
| | An array of plugins to activate. See Using Plugins section |jsx
| | Set to true to enable JSX parsing. Default false |
Found TypeScript definition here.
Given the folowing SFC file test/examples/circle-drawer/circle-drawer-composition.vue, the parsing usage would be:
`js
import { parseComponent } from '@vuedoc/parser';
const options = {
filename: 'test/examples/circle-drawer/circle-drawer-composition.vue',
};
parseComponent(options)
.then((component) => console.log(component))
.catch((err) => console.error(err));
`
This will print this JSON output:
`js`
{
"name": "CircleDrawer",
"description": "Circle Drawer’s goal is, among other things, to test how good the common\nchallenge of implementing an undo/redo functionality for a GUI application\ncan be solved.",
"see": "https://eugenkiss.github.io/7guis/tasks/#circle",
"inheritAttrs": true,
"errors": [],
"warnings": [],
"keywords": [
{
"name": "usage",
"description": "Click on the canvas to draw a circle. Click on a circle to select it.\nRight-click on the canvas to adjust the radius of the selected circle."
}
],
"props": [ / ... / ],
"data": [ / ... / ],
"computed": [ / ... / ],
"slots": [ / ... / ],
"events": [ / ... / ],
"methods": [ / ... / ]
}
> Found the complete result here: test/examples/circle-drawer/parsing-result.json
> Found more examples here: test/examples
`sh`
-j, --join # Combine generated documentation for multiple component files into only one
-c, --config
-o, --output
--ignore-name # Ignore the component name on parsing
--ignore-description # Ignore the component description on parsing
--ignore-keywords # Ignore the component keywords on parsing
--ignore-slots # Ignore the component slots on parsing
--ignore-props # Ignore the component props on parsing
--ignore-computed # Ignore the component computed properties on parsing
--ignore-data # Ignore the component data on parsing
--ignore-methods # Ignore the component methods on parsing
--ignore-events # Ignore the component events on parsing
Overwrite Vuedoc Parser configuration using vuedoc.config.js
`js
// vuedoc.config.js
import { Loader } from '@vuedoc/parser';
import { PugLoader } from '@vuedoc/parser/loaders/pug';
export default {
output: 'docs/',
parsing: {
features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'events', 'methods'],
loaders: [
Loader.extend('pug', PugLoader),
],
},
};
`
`shdisplay the Vuedoc version
vuedoc-json --version
Syntax
$3
By default, Vuedoc Parser uses the component's filename to generate the
component name.
option:`html
`You can also use the
tag:`html
`Composition usage
When using
$3
To add a component description, just add a comment before the
statement like:html
`When using
$3
To document props, annotate your code like:
Legacy usage
html
`Vuedoc Parser will automatically extract
, required and default values for
properties.Composition usage
`html
`Vuedoc Parser will automatically extract
, required and default values for
properties.Composition usage with TypeScript
`html
`Vuedoc Parser will automatically extract
, required and default values from
the type definition.#### Annotate a
v-model propLegacy usage
`html
`Composition usage
To document a
prop using Composition API, use
defineProps()
macro.`html
`Vue 2 usage
To document a
prop legacy Vue, use the Vue's
model field.`html
`#### Annotate Vue Array String Props
To document Vue array string props, just attach a Vuedoc comment to each prop:
Legacy usage
html
`Composition usage
html
`#### Special tags for props
-
Commented prop will use provided type name as type instead of type in source
code. This option may be helpful in case the prop type is a complex object or
a function
-
Commented prop will use the provided value as default prop value. This option
may be helpful in case the prop type is a complex object or function
-
Force parsing of a prop as a functionhtml
`#### Prop Entry Interface
ts
interface PropEntry {
kind: 'prop';
name: string;
type: string | string[];
default: string;
required: boolean;
description?: string;
describeModel: boolean;
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
`$3
To document data, annotate your code like:
Legacy usage
html
`Composition usage
html
`Vuedoc Parser will automatically detect type for each defined data field and
catch their initial value.
Special tags for data
-
Commented data will use provided type name as type instead of type in source
code. This option may be helpful in case the data type is a complex object or
a function
-
Commented data will use the provided value as initial data value. This option
may be helpful in case the data type is a complex object or functionhtml
`Data Entry Interface
ts
interface DataEntry {
kind: 'data';
name: string;
type: string;
initialValue: string;
description?: string;
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
`$3
To document computed properties, annotate your code like:
Legacy usage
html
`Vuedoc Parser will automatically extract computed properties dependencies.
Composition usage
html
`Usage with
Computed Property Entry Interface
ts
interface ComputedEntry {
kind: 'computed';
name: string;
type: string;
dependencies: string[];
description?: string;
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
`$3
and
@returns:Legacy usage
`html
`Composition usage
html
`Special tags for methods
-
You can use special tag for non primitive name:
`html
`-
By default, Vuedoc Parser automatically generates method syntax with typing.
For example, the previous example will generate:
js
{
kind: 'method',
name: 'closeModal',
params: [],
returns: { type: 'void', description: undefined },
syntax: [
'closeModal(): void'
],
category: undefined,
version: undefined,
description: undefined,
keywords: [],
visibility: 'public'
}
`
You can overwrite syntax generation by using tag . You can also
define multiple syntax examples:
`html
`Method Entry Interface
ts
interface MethodEntry {
kind: 'method';
name: string;
params: MethodParam[];
returns: MethodReturn;
syntax: string[];
description?: string;
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
type MethodParam = {
name: string;
type: NativeTypeEnum | string;
description?: string;
defaultValue?: string;
rest: boolean;
};
type MethodReturn = {
type: string;
description?: string;
};
`$3
Legacy usage
To document events using the legacy syntax, use the
emits
field and tags
or @argument to define arguments:Array syntax:
`html
`Object syntax with validation:
html
`Composition usage
Array syntax:
html
`Object syntax with validation:
html
`Composition usage with TypeScript
html
`Vue 2 usage
Vuedoc Parser automatically extracts events from component template, hooks and
methods when using Vue 2:
html
`You can use special keyword
for non primitive name:`html
`Event Entry Interface
ts
interface EventEntry {
kind: 'event';
name: string;
description?: string;
arguments: EventArgument[];
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
type EventArgument = {
name: string;
type: NativeTypeEnum | string;
description?: string;
rest: boolean;
};
`$3
Vuedoc Parser automatically extracts slots from template. You must use
tag to define properties of a slot:html
Unnamed checkbox
`Annotate slots defined in Render Functions
To annotate slots defined in Render Functions, just attach the tag
to the component definition:html
`You can also use the tag
to define dynamic slots on template:`html
`Slot Entry Interface
ts
interface SlotEntry {
kind: 'slot';
name: string;
description?: string;
props: SlotProp[];
keywords: Keyword[];
category?: string;
version?: string;
since?: string;
visibility: 'public' | 'protected' | 'private';
}type Keyword = {
name: string;
description?: string;
};
type SlotProp = {
name: string;
type: string;
description?: string;
};
`$3
Use the JSDoc's tag
to keeps the
subsequent code from being documented.`html
`You can also use the TypeDoc's tag
.Tags Extraction
You can attach keywords (or tags) to any comment and then extract them using
the parser.
Usage
`html
`> Note that the description must always appear before keywords definition.
Parsing result:
json
{
"name": "my-checkbox",
"description": "Component description",
"keywords": [
{
"name": "license",
"description": "MIT"
}
]
}
`Supported Tags
| Tag | Scope | Description |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------ |
|
| component | Provide a custom name of the component |
| @type | props, data, computed | Provide a type expression identifying the type of value that a prop or a data may contain |
| @default | props | Provide a default value of a prop |
| @kind | props | Used to document what kind of symbol is being documented |
| @initialValue | data | Provide an initial value of a data |
| @method | methods | Force the name of a specific method |
| @syntax | methods | Provide the custom method syntax |
| @param | methods | Provide the name, type, and description of a function parameter |
| @returns, @return | methods | Document the value that a function returns |
| @event | events | Force the name of a specific event |
| @arg, @argument | events | Provide the name, type, and description of an event argument |
| @slot | slots | Document slot defined in render function |
| @prop | slots | Provide the name, type, and description of a slot prop |
| @mixin deprecated | component | Force parsing of the exported item as a mixin component. This is deprecated since v4.0.0 |
| @version | all | Assign a version to an item |
| @since | all | Indicate that an item was added in a specific version |
| @author | all | Identify authors of an item |
| @deprecated | all | Mark an item as being deprecated |
| @see | all | Allow to refer to a resource that may be related to the item being documented |
| @ignore | * | Keep the subsequent code from being documented |
| TypeDoc | | |
| @category | all | Attach a category to an item |
| @hidden | * | Keep the subsequent code from being documented |
| Visibilities | | |
| @public | * | Mark a symbol as public |
| @protected | * | Mark a symbol as private |
| @private | * | Mark a symbol as protected |>
* stand for props, data, methods, events, slotsWorking with Mixins
Starting
, Vuedoc Parser implements a mechanism to automatically
load needed import declarations to parse and extract metadata.With this new capability, Vuedoc Parser is now able to handle Vue mixins
automatically.
Parsing control with
options.features lets you select which Vue Features you want to parse and
extract.The default value is defined by
VuedocParser.SUPPORTED_FEATURES array.Usage
Only parse
name, props, computed properties, slots and events:`js
import { parseComponent } from '@vuedoc/parser';const options = {
filename: 'test/examples/circle-drawer/circle-drawer-composition.vue',
features: [ 'name', 'props', 'computed', 'slots', 'events' ],
};
parseComponent(options)
.then((component) => Object.keys(component))
.then((keys) => console.log(keys));
// => [ 'name', 'props', 'computed', 'slots', 'events' ]
`Parse all features except
:`js
import { parseComponent, VuedocParser } from '@vuedoc/parser';const options = {
filename: 'test/examples/circle-drawer/circle-drawer-composition.vue',
features: VuedocParser.SUPPORTED_FEATURES.filter((feature) => feature !== 'data'),
};
parseComponent(options)
.then((component) => Object.keys(component))
.then((keys) => console.log(keys));
// => [ 'name', 'description', 'keywords', 'model',
// 'props', 'computed', 'events', 'methods', 'slots' ]
`Using Plugins
Vuedoc can be extended using plugins.
$3
To use a plugin, it needs to be added to the
of the project
and included in the plugins array options.plugins. For example, to provide
support of Vue Router, the official @vuedoc/plugin-vue-router
can be used:sh
$ npm add -D @vuedoc/plugin-vue-router
`js
// main.js
import { parseComponent } from '@vuedoc/parser';
import { VueRouterPlugin } from '@vuedoc/plugin-vue-router';const component = await parseComponent({
plugins: [
VueRouterPlugin,
],
// ...
});
`$3
| Name | Description | Documentation |
| ----------------- | -------------------------------- | -------------------------------------------------------------------------- |
| Vue Router Plugin | The Vue Router plugin for Vuedoc |
|
| Vuex Plugin | The Vuex plugin for Vuedoc | @vuedoc/plugin-vuex |$3
Plugins Overview
A Vuedoc plugin is an object with one or more of the properties, parsing hooks
described below, and which follows our conventions.
A plugin should be distributed as a package which exports a function
that can be called with plugin specific options and returns such an
object.
Plugins allow you to customise Vuedoc's behaviour by, for example,
handling and parse parsing result object before sending the final result, or
adding support of a third-party modules in your
node_modules folder.Conventions
- Plugins should have a clear name with
vuedoc-plugin- prefix.
- Include vuedoc-plugin keyword in package.json.
- Plugins should be tested.
- Document your plugin in English.Interface
`ts
type Plugin = (parser: Parser) => PluginDefinition;interface PluginDefinition {
/**
* Custom import resolver
*/
resolver?: ImportResolver;
/**
* List of resource files to preload before parsing
*/
preload?: string[];
/**
* Additional composition tokens for advanced components
*/
composition?: Partial;
/**
* Handle parsing result
*/
handleParsingResult?(component: ParseResult): void;
}
interface Parser extends EventTarget {
/**
* Resolved options
*/
readonly options: ResolvedOptions;
addEventListener(
type: EventType,
callback: EventListener>,
options?: boolean | AddEventListenerOptions
): void;
addEventListener(
type: EventType,
callback: EventListener>,
options?: boolean | AddEventListenerOptions
): void;
addEventListener(
type: 'end',
callback: EventListener,
options?: boolean | AddEventListenerOptions
): void;
): void;
addEventListener(
type: 'fatal',
callback: EventListener,
options?: boolean | AddEventListenerOptions
): void;
}
type EventType = 'computed' | 'data' | 'description' | 'event' | 'inheritAttrs' | 'keyword' | 'method' | 'model' | 'name' | 'prop';
`Please see PluginInterface from types/index.d.ts from detailled types.
Language Processing
$3
Please see TypeScript definition file for the Loader class.
$3
| Language | Load by default? | Module |
| ---------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| HTML | Yes | @vuedoc/parser/loaders/html |
| JavaScript | Yes | @vuedoc/parser/loaders/javascript |
| Pug | No | @vuedoc/parser/loaders/pug |
| TypeScript | Yes | @vuedoc/parser/loaders/typescript |
| Vue | Yes | @vuedoc/parser/loaders/vue |
$3
The example below uses the abstract
class to create a
specialized class to handle a template with the
CoffeeScript language.
It uses the built-in PugLoader to load Pug template:`js
import { parseComponent, Loader } from '@vuedoc/parser';
import { PugLoader } from '@vuedoc/parser/loaders/pug';
import { compile } from 'coffeescript';class CoffeeScriptLoader extends Loader {
load (source) {
const outputText = compile(source);
this.emitScript(outputText);
}
}
const options = {
filecontent:
,lang
loaders: [
/**
* Register CoffeeScriptLoader
* Note that the name of the loader is either the extension
* of the file or the value of the attribute
*/
Loader.extend('coffee', CoffeeScriptLoader),
// Register the built-in Pug loader
Loader.extend('pug', PugLoader),
],
};
parseComponent(options).then((component) => {
console.log(component);
});
`
Output
`js`
{
name: 'MyInput',
description: 'Description of MyInput component',
slots: [
{
kind: 'slot',
visibility: 'public',
description: 'Use this slot to define a subtitle',
keywords: [],
name: 'subtitle',
props: []
}
],
// ...
}
Please see TypeScript definition file.
To generate a markdown documentation, please use the @vuedoc/md package.
Please follow CONTRIBUTING.md.
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,MINOR
- version when you add functionality in a backwards-compatible manner,PATCH
and
- version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions
to the MAJOR.MINOR.PATCH` format.
See SemVer.org for more details.
Under the MIT license.
See LICENSE file for
more details.