Generate a JSON documentation for a Vue file component
npm install --save @vuedoc/parser
@
symbol like @author Jon Snow
@param
and @return
tags)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. |
Default features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'data', 'computed', 'events', 'methods'] |
|
loaders | Use this option to define custom loaders for specific languages |
defaultMethodVisibility | Can be set to 'public' (default), 'protected' , or 'private' |
ignoredVisibilities | List of ignored visibilities. Default: ['protected', 'private'] |
stringify | Set to true to disable parsing of literal values and stringify literal values. Default: false |
Note for stringify
option
By default Vuedoc Parser parses literal values defined in the source code. This means:
const binVar = 0b111110111 // will be parsed as binVar = 503
const numVar = 1_000_000_000 // will be parsed as numVar = 1000000000
To preserve literal values, set the stringify
option to true
.
See test/fixtures/checkbox.vue for an Vue Component decoration example.
const Vuedoc = require('@vuedoc/parser')
const options = {
filename: 'test/fixtures/checkbox.vue'
}
Vuedoc.parse(options)
.then((component) => console.log(component))
.catch((err) => console.error(err))
This will print this JSON output:
{
"name": "checkbox" // The component name
"description": "A simple checkbox component" // The component description
// Attached component keywords
"keywords": [
{ "name": "author", "description": "Sébastien" }
],
"props": [ ... ],
"data": [ ... ],
"computed": [ ... ],
"slots": [ ... ],
"events": [ ... ],
"methods": [ ... ]
}
See test/fixtures/checkbox-result.json for the complete result.
By default, Vuedoc Parser use the component’s filename to generate the component name.
To set a custom name, use the name
field like:
export default {
name: 'my-checkbox'
}
You can also use the @name
keyword to set the component name:
/**
* @name my-checkbox
*/
export default {
// ...
}
To add a component description, just add a comment before the export default
statement like:
/**
* Component description
*/
export default {
...
}
To document props, data or computed properties, use comments like:
export default {
props: {
/**
* Component ID
*/
id: {
type: String,
required: true
}
},
data () {
return {
/**
* Indicates that the control is checked
*/
isChecked: false
}
},
computed: {
/**
* Indicates that the control is selected
*/
selected () {
return this.isChecked
}
}
}
Vuedoc Parser will automatically extract required
and default
values for properties and computed properties dependencies. It will also detect type for each defined data field.
You can set a custom default value of an prop by using the keyword @default
.
export default {
props: {
/**
* Custom default value
* @default { anything: 'custom default value' }
*/
custom: {
type: String,
default: () => {
// complex code
return anythingExpression()
}
}
}
}
To document a v-model
prop, a proper way is to use the Vue’s model field if you use Vue +2.2.0.
export default {
/**
* Use `v-model` to define a reactive value of the checkbox
*/
model: {
prop: 'checked',
event: 'change'
}
}
You can also use the @model
keyword on a prop if you use an old Vue version:
export default {
props: {
/**
* The checkbox model
* @model
*/
model: {
type: Array,
required: true
}
}
}
To document Vue array string props, just attach a Vuedoc comment to each prop:
export default {
props: [
/**
* Checkbox ID
*/
'id',
/**
* The checkbox model
*/
'value'
]
}
By default, all extracted things have the public
visibility. To change this for one entry, add @protected
or @private
keyword.
export default {
data: () => ({
/**
* This will be ignored on parsing
* @private
*/
isChecked: false
})
}
To document methods or events, just add comments before:
export default {
methods: {
/**
* Submit form
*/
check () {
/**
* Emit the `input` event on submit
*/
this.$emit('input', true)
}
}
}
Vuedoc Parser automatically extracts events from component hooks:
export default {
created () {
/**
* Emit on Vue `created` hook
*/
this.$emit('created', true)
}
}
Use the JSDoc @param and @return tags to define parameters and returning type:
export default {
methods: {
/**
* Submit form
*
* @param {object} data - Data to submit
* @return {boolean} true on success; otherwise, false
*/
submit (data) {
/**
* Emit the `loading` event on submit
*
* @arg {boolean} status - The loading status
*/
this.$emit('loading', true)
return true
}
}
}
Note:
@arg
is an alias of@param
The parser is also able to extract events and slots from template:
<template>
<div>
<!-- Emit the `input` event on submit -->
<button @click="$emit('input', $event)">Submit</button>
<!-- Default slot -->
<slot></slot>
<!-- Use this slot to set the checkbox label -->
<slot name="label">Unnamed checkbox</slot>
<!--
Slot with keywords and
multiline description
@prop {User} user - The current user
@prop {UserProfile} profile - The current user's profile
-->
<slot name="header" v-bind:user="user" v-bind:profile="profile"/>
</div>
</template>
Usage with non primitive name
You can use special keywords @method
and @event
for non primitive name:
<script>
const METHODS = {
CLOSE: 'closeModal'
}
const EVENTS = {
CLOSE: 'close'
}
export default {
methods: {
/**
* Close modal
* @method closeModal
*/
[METHODS.CLOSE] () {
/**
* Emit the `close` event on click
* @event close
*/
this.$emit(EVENTS.CLOSE, true)
}
}
}
</script>
To annotate slots defined in Render Functions, just attach the keyword @slot
to the component definition:
/**
* A functional component with slots defined in render function
* @slot title - A title slot
* @slot default - A default slot
*/
export default {
functional: true,
render(h, { slots }) {
return h('div', [
h('h1', slots().title),
h('p', slots().default)
])
}
}
You can also use the keyword @slot
to define dynamic slots on template:
<template>
<div>
<template v-for="name in ['title', 'default']">
<!--
@slot title - A title slot
@slot default - A default slot
-->
<slot :name="name" :slot="name"></slot>
</template>
</div>
</template>
You can attach keywords to any comment and then extract them using the parser.
Usage
/**
* Component description
*
* @author Arya Stark
* @license MIT
*/
export default { ... }
Note that the description must alway appear before keywords definition
Parsing result:
{
"name": "my-checkbox",
"description": "Component description",
"keywords": [
{
"name": "author",
"description": "Arya Stark"
},
{
"name": "license",
"description": "MIT"
}
]
}
Since Vuedoc Parser don’t perform I/O operations, it completely ignores the mixins
property.
To parse a mixin, you need to parse its file as a standalone component and then merge the parsing result with the result of the initial component:
const Vuedoc = require('@vuedoc/parser')
const merge = require('deepmerge')
const parsers = [
Vuedoc.parse({ filename: 'mixinFile.js' })
Vuedoc.parse({ filename: 'componentUsingMixin.vue' })
]
Promise.all(parsers)
.then(merge.all)
.then((mergedParsingResult) => console.log(mergedParsingResult))
.catch((err) => console.error(err))
Using the keyword @mixin
You can use the special keyword @mixin
to force parsing named exported component:
import Vue from 'vue';
/**
* @mixin
*/
export const InputMixin = Vue.extend({
props: {
id: String,
Value: [ Boolean, Number, String ]
}
});
options.features
lets you select which Vue Features you want to parse and extract.
The default value is defined by Vuedoc.Parser.SUPPORTED_FEATURES
array.
Usage
Only parse name
, props
, computed properties
, slots
and events
:
const Vuedoc = require('@vuedoc/parser')
const options = {
filename: 'test/fixtures/checkbox.vue',
features: [ 'name', 'props', 'computed', 'slots', 'events' ]
}
Vuedoc.parse(options)
.then((component) => Object.keys(component))
.then((keys) => console.log(keys))
// => [ 'name', 'props', 'computed', 'slots', 'events' ]
Parse all features except data
:
const Vuedoc = require('@vuedoc/parser')
const options = {
filename: 'test/fixtures/checkbox.vue',
features: Vuedoc.Parser.SUPPORTED_FEATURES.filter((feature) => feature !== 'data')
}
Vuedoc.parse(options)
.then((component) => Object.keys(component))
.then((keys) => console.log(keys))
// => [ 'name', 'description', 'keywords', 'model',
// 'props', 'computed', 'events', 'methods', 'slots' ]
abstract class Loader {
public static extend(loaderName: string, loaderClass: Loader);
public abstract load(source: string): Promise<void>;
public emitTemplate(source: string): Promise<void>;
public emitScript(source: string): Promise<void>;
public emitErrors(errors: Array<string>): Promise<void>;
public pipe(loaderName: string, source: string): Promise<void>;
}
Language | Load by default? | Package |
---|---|---|
HTML | Yes | @vuedoc/parser/loader/html |
JavaScript | Yes | @vuedoc/parser/loader/javascript |
Pug | No | @vuedoc/parser/loader/pug |
TypeScript | No | @vuedoc/parser/loader/typescript |
Vue | Yes | @vuedoc/parser/loader/vue |
The Vuedoc Parser package contains a loader for TypeScript. To use it, you need to:
typescript
and @types/node
dependencies according the official documentation@vuedoc/parser/loader/typescript
const Vuedoc = require('@vuedoc/parser')
const TypeScriptLoader = require('@vuedoc/parser/loader/typescript')
const options = {
filename: 'DatePicker.ts',
loaders: [
/**
* Register TypeScriptLoader
* Note that the name of the loader is either the extension
* of the file or the value of the attribute `lang`
*/
Vuedoc.Loader.extend('ts', TypeScriptLoader)
]
}
Vuedoc.parse(options).then((component) => {
console.log(component)
})
The example below uses the abstract Vuedoc.Loader
class to create a specialized class to handle a template with the CoffeeScript language. It uses the Pug language for templating:
const Vuedoc = require('@vuedoc/parser')
const PugLoader = require('@vuedoc/parser/loader/pug')
const CoffeeScript = require('coffeescript')
class CoffeeScriptLoader extends Vuedoc.Loader {
load (source) {
const outputText = CoffeeScript.compile(source);
// don't forget the return here
return this.emitScript(outputText);
}
}
const options = {
filecontent: `
<template lang="pug">
div.page
h1 Vuedoc Parser with Pug
// Use this slot to define a subtitle
slot(name='subtitle')
</template>
<script lang="coffee">
###
# Description of MyInput component
###
export default
name: 'MyInput'
</script>
`,
loaders: [
/**
* Register CoffeeScriptLoader
* Note that the name of the loader is either the extension
* of the file or the value of the attribute `lang`
*/
Vuedoc.Loader.extend('coffee', CoffeeScriptLoader),
// Register the Pug loader
Vuedoc.Loader.extend('pug', PugLoader)
]
}
Vuedoc.parse(options).then((component) => {
console.log(component)
})
Output
{
name: 'MyInput',
description: 'Description of MyInput component',
slots: [
{
kind: 'slot',
visibility: 'public',
description: 'Use this slot to define a subtitle',
keywords: [],
name: 'subtitle',
props: []
}
],
// ...
}
type ParsingOutput = {
name: string; // Component name
description: string; // Component description
inheritAttrs: boolean;
keywords: Keyword[]; // Attached component keywords
model?: ModelEntry; // Component model
slots: SlotEntry[]; // Component slots
props: PropEntry[]; // Component props
data: DataEntry[]; // Component data
computed: ComputedEntry[]; // Computed properties
events: EventEntry[]; // Events
methods: MethodEntry[]; // Component methods
errors: string[]; // Syntax and parsing errors
};
enum NativeTypeEnum {
string,
number,
bigint,
boolean,
bigint,
any, // for an explicit `null` or `undefined` values
object, // for an array or an object
CallExpression // for a value like `new Date()`
};
type Keyword = {
name: string;
description: string;
}
interface Entry {
kind: 'computed' | 'data' | 'event' | 'method' | 'model' | 'prop' | 'slot';
visibility: 'public' | 'protected' | 'private';
description: string;
keywords: Keyword[];
}
interface ModelEntry extends Entry {
kind: 'model';
prop: string;
event: string;
}
interface SlotEntry extends Entry {
kind: 'slot';
name: string;
props: SlotProp[];
}
type SlotProp = {
name: string;
type: string;
description: string;
};
interface ModelEntry extends Entry {
kind: 'model';
prop: string;
event: string;
}
interface PropEntry extends Entry {
kind: 'prop';
name: string; // v-model when the @model keyword is attached
type: string | string[]; // ex. Array, Object, String, [String, Number]
nativeType: NativeTypeEnum;
default?: string;
required: boolean = false;
describeModel: boolean; // true when the @model keyword is attached
}
interface DataEntry extends Entry {
kind: 'data';
name: string;
type: NativeTypeEnum;
initial?: string;
}
interface ComputedEntry extends Entry {
kind: 'computed';
name: string;
dependencies: string[]; // list of dependencies of the computed property
}
interface EventEntry extends Entry {
kind: 'event';
name: string;
arguments: EventArgument[];
}
type EventArgument = {
name: string;
description: string;
type: string;
};
interface MethodEntry extends Entry {
kind: 'method';
name: string;
params: MethodParam[];
return: MethodReturn;
}
type MethodParam = {
type: string;
name: string;
description: string;
defaultValue?: string;
}
type MethodReturn = {
type: string = 'void';
description: string;
};
Contributions to Vuedoc Parser are welcome. Here is how you can contribute:
dev
branch: git checkout dev -b feature/my-awesome-feature
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, andPATCH
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.
Author: vuedoc
GitHub: https://github.com/vuedoc/parser
#vuejs #javascript #vue-js #vue