Package Exports
- vue-docgen-api
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vue-docgen-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
vue-docgen-api
vue-docgen-api is a toolbox to help extracting information from Vue components, and generate documentation from it.
Use @babel/parser to parse the code and analyze the contents of the component extracting methods, props events and slots. The output is a JavaScript object.
Install
Install the module directly from npm:
npm install vue-docgen-api --save-devAPI
The tool can be used programmatically to extract component information and customize the extraction process:
var vueDocs = require('vue-docgen-api')
var componentInfo
vueDocs.parse(filePath).then(ci => {
componentInfo = ci
})or with typescript
import { parse } from 'vue-docgen-api'
async function parseMyComponent(filePath: string) {
var componentInfoSimple = await parse(filePath)
var componentInfoConfigured = await parse(filePath, {
alias: { '@assets': path.resolve(__dirname, 'src/assets') },
resolve: [path.resolve(__dirname, 'src')],
addScriptHandler: [
function(
documentation: Documentation,
componentDefinition: NodePath,
astPath: bt.File,
opt: ParseOptions
) {
// handle custom code in script
}
],
addTemplateHandler: [
function(
documentation: Documentation,
templateAst: ASTElement,
options: TemplateParserOptions
) {
// handle custom directives here
}
]
})
}parse() vs parseMulti()
The API exports two asynchronous functions parse and parseMulti. The two functions take the same set of parameters. parse returns a pure ComponentDoc whereas parseMulti returns an array of ComponentDoc
When using only SFC or components that are the only one in their components, this function returns a ComponentDoc object. Using parse in most cases is simpler.
If you are creating a library and your goal is to have it as generic as possible, it might be a good idea to use parseMulti. In some cases, developer choose to have more than one component exported by a file, which make parse throw an error.
Using JSDoc tags
You can use JSDoc tags when documenting components, props and methods.
Props
export default {
props: {
/**
* Color of the button.
*/
color: {
type: String,
default: '#FCC'
},
/**
* initial value to be passed but undocumented
* @ignore
*/
initialvalue: {
type: Number,
default: 0
},
/**
* The size of the button allows only some values
* @values small, medium, large
*/
size: {
default: 'normal'
}
}
}Events
export default {
methods: {
emitSuccess() {
/**
* Success event.
*
* @event success
* @property {string} content content of the first prop passed to the event
* @property {object} example the demo example
*/
this.$emit('success', content, {
demo: 'example'
})
}
}
}Slots
<template>
<div>
<!-- @slot Use this slot header -->
<slot name="header"></slot>
<!--
@slot Modal footer
@binding item an item passed to the footer
-->
<slot name="footer" :item="item" />
</div>
</template>Full Example
For the following component
<template>
<div>
<!-- @slot Use this slot header -->
<slot name="header"></slot>
<table class="grid">
<!-- -->
</table>
<!--
@slot Modal footer
@binding item an item passed to the footer
-->
<slot name="footer" :item="item" />
</div>
</template>
<script>
import { text } from './utils'
/**
* This is an example of creating a reusable grid component and using it with external data.
* @version 1.0.5
* @author [Rafael](https://github.com/rafaesc92)
* @since Version 1.0.1
*/
export default {
name: 'grid',
props: {
/**
* object/array defaults should be returned from a factory function
* @version 1.0.5
* @since Version 1.0.1
* @see See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names
* @link See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names
*/
msg: {
type: [String, Number],
default: text
},
/**
* Model example
* @model
*/
value: {
type: String
},
/**
* describe data
* @version 1.0.5
*/
data: [Array],
/**
* get columns list
*/
columns: [Array],
/**
* filter key
* @ignore
*/
filterKey: {
type: String,
default: 'example'
}
},
data() {
var sortOrders = {}
this.columns.forEach(function(key) {
sortOrders[key] = 1
})
return {
sortKey: '',
sortOrders: sortOrders
}
},
computed: {
filteredData: function() {
var sortKey = this.sortKey
var filterKey = this.filterKey && this.filterKey.toLowerCase()
var order = this.sortOrders[sortKey] || 1
var data = this.data
if (filterKey) {
data = data.filter(function(row) {
return Object.keys(row).some(function(key) {
return (
String(row[key])
.toLowerCase()
.indexOf(filterKey) > -1
)
})
})
}
if (sortKey) {
data = data.slice().sort(function(a, b) {
a = a[sortKey]
b = b[sortKey]
return (a === b ? 0 : a > b ? 1 : -1) * order
})
}
return data
}
},
filters: {
capitalize: function(str) {
return str.charAt(0).toUpperCase() + str.slice(1)
}
},
methods: {
/**
* Sets the order
*
* @public
* @version 1.0.5
* @since Version 1.0.1
* @param {string} key Key to order
* @returns {string} Test
*/
sortBy: function(key) {
this.sortKey = key
this.sortOrders[key] = this.sortOrders[key] * -1
/**
* Success event.
*
* @event success
* @type {object}
*/
this.$emit('success', {
demo: 'example'
})
},
hiddenMethod: function() {}
}
}
</script>we are getting this output:
const componentDoc = {
displayName: 'grid',
description:
'This is an example of creating a reusable grid component and using it with external data.',
tags: {
version: [
{
description: '1.0.5',
title: 'version'
}
],
author: [
{
description: '[Rafael](https://github.com/rafaesc92)',
title: 'author'
}
],
since: [
{
description: 'Version 1.0.1',
title: 'since'
}
]
},
exportName: 'default',
props: [
{
description:
'object/array defaults should be returned from a factory function',
tags: {
version: [
{
description: '1.0.5',
title: 'version'
}
],
since: [
{
description: 'Version 1.0.1',
title: 'since'
}
],
see: [
{
description:
'See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names',
title: 'see'
}
],
link: [
{
description:
'See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names',
title: 'link'
}
]
},
name: 'msg',
type: {
name: 'string|number'
},
defaultValue: {
func: false,
value: 'text'
}
},
{
description: 'Model example',
tags: {
model: [
{
description: true,
title: 'model'
}
]
},
name: 'v-model',
type: {
name: 'string'
}
},
{
description: 'describe data',
tags: {
version: [
{
description: '1.0.5',
title: 'version'
}
]
},
name: 'data',
type: {
name: 'array'
}
},
{
description: 'get columns list',
tags: {},
name: 'columns',
type: {
name: 'array'
}
},
{
description: 'filter key',
tags: {
ignore: [
{
description: true,
title: 'ignore'
}
]
},
name: 'filterKey',
type: {
name: 'string'
},
defaultValue: {
func: false,
value: "'example'"
}
}
],
events: [
{
name: 'success',
description: 'Success event.',
type: {
names: ['object']
}
}
],
methods: [
{
name: 'sortBy',
modifiers: [],
description: 'Sets the order',
tags: {
access: [
{
description: 'public',
title: 'access'
}
],
version: [
{
description: '1.0.5',
title: 'version'
}
],
since: [
{
description: 'Version 1.0.1',
title: 'since'
}
],
params: [
{
title: 'param',
type: {
name: 'string'
},
name: 'key',
description: 'Key to order'
}
],
returns: [
{
title: 'returns',
type: {
name: 'string'
},
description: 'Test'
}
]
},
params: [
{
name: 'key',
type: {
name: 'string'
},
description: 'Key to order'
}
],
returns: {
title: 'returns',
type: {
name: 'string'
},
description: 'Test'
}
}
],
slots: [
{
name: 'header',
description: 'Use this slot header'
},
{
name: 'footer',
description: 'Modal footer',
scoped: true,
bindings: [
{
title: 'binding',
type: {
name: 'mixed'
},
name: 'item',
description: 'an item passed to the footer'
}
]
}
]
}Change log
The change log can be found on the Changelog Page.
Authors and license
MIT License.