62 | >
63 | // if there is no type annotation, get it from the decorators arguments
64 | if (!propPath.node.typeAnnotation) {
65 | describeType(propsPath, propDescriptor)
66 | }
67 | describeDefault(propsPath, propDescriptor)
68 | describeRequired(propsPath, propDescriptor)
69 | }
70 | }
71 | })
72 | }
73 | }
74 |
--------------------------------------------------------------------------------
/src/template-handlers/__tests__/propHandler.ts:
--------------------------------------------------------------------------------
1 | import { compile } from 'vue-template-compiler'
2 | import { Documentation } from '../../Documentation'
3 | import { traverse } from '../../parse-template'
4 | import propHandler from '../propHandler'
5 |
6 | describe('slotHandler', () => {
7 | let doc: Documentation
8 | beforeEach(() => {
9 | doc = new Documentation()
10 | })
11 |
12 | it('should match props in attributes expressions', () => {
13 | const ast = compile(
14 | [
15 | '',
16 | '
titleof the template
',
17 | ' ',
18 | ' ',
19 | ' ',
20 | '',
21 | ].join('\n'),
22 | { comments: true },
23 | ).ast
24 | if (ast) {
25 | traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
26 | expect(doc.toObject().props).toMatchObject({
27 | size: { type: { name: 'number' }, description: 'width of the button' },
28 | value: { type: { name: 'string' }, description: 'value in the form' },
29 | })
30 | } else {
31 | fail()
32 | }
33 | })
34 |
35 | it('should match props in interpolated text', () => {
36 | const ast = compile(
37 | [
38 | '',
39 | '
titleof the template
',
40 | ' ',
45 | '',
46 | ].join('\n'),
47 | { comments: true },
48 | ).ast
49 | if (ast) {
50 | traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
51 | expect(doc.toObject().props).toMatchObject({
52 | name: { type: { name: 'mixed' }, description: 'Your Name' },
53 | adress: { type: { name: 'string' }, description: 'Your Adress' },
54 | })
55 | } else {
56 | fail()
57 | }
58 | })
59 |
60 | it('should not match props if in a string litteral', () => {
61 | const ast = compile(
62 | [
63 | '',
64 | '
titleof the template
',
65 | ' ',
67 | ].join('\n'),
68 | { comments: true },
69 | ).ast
70 | if (ast) {
71 | traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
72 | expect(doc.toObject().props).toBeUndefined()
73 | } else {
74 | fail()
75 | }
76 | })
77 |
78 | it('should not match props if in a non evaluated attribute', () => {
79 | const ast = compile(
80 | [
81 | '',
82 | '
titleof the template
',
83 | ' ',
85 | ].join('\n'),
86 | { comments: true },
87 | ).ast
88 | if (ast) {
89 | traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
90 | expect(doc.toObject().props).toBeUndefined()
91 | } else {
92 | fail()
93 | }
94 | })
95 | })
96 |
--------------------------------------------------------------------------------
/src/script-handlers/__tests__/extendsHandler.ts:
--------------------------------------------------------------------------------
1 | import * as bt from '@babel/types'
2 | import babylon from '../../babel-parser'
3 | jest.mock('../../utils/resolveRequired')
4 | jest.mock('../../utils/resolvePathFrom')
5 | jest.mock('../../parse')
6 | import { Documentation } from '../../Documentation'
7 | import { parseFile } from '../../parse'
8 | import resolveExportedComponent from '../../utils/resolveExportedComponent'
9 | import resolvePathFrom from '../../utils/resolvePathFrom'
10 | import resolveRequired from '../../utils/resolveRequired'
11 | import extendsHandler from '../extendsHandler'
12 |
13 | describe('extendsHandler', () => {
14 | let resolveRequiredMock: jest.Mock
15 | let mockResolvePathFrom: jest.Mock
16 | let mockParse: jest.Mock
17 | const doc = new Documentation()
18 | beforeEach(() => {
19 | resolveRequiredMock = resolveRequired as jest.Mock<
20 | (ast: bt.File, varNameFilter?: string[]) => { [key: string]: string }
21 | >
22 | resolveRequiredMock.mockReturnValue({
23 | testComponent: { filePath: './componentPath', exportName: 'default' },
24 | })
25 |
26 | mockResolvePathFrom = resolvePathFrom as jest.Mock<(path: string, from: string) => string>
27 | mockResolvePathFrom.mockReturnValue('./component/full/path')
28 |
29 | mockParse = parseFile as jest.Mock
30 | mockParse.mockReturnValue({ component: 'documentation' })
31 | })
32 |
33 | function parseItExtends(src: string) {
34 | const ast = babylon().parse(src)
35 | const path = resolveExportedComponent(ast).get('default')
36 | if (path) {
37 | extendsHandler(doc, path, ast, { filePath: '' })
38 | }
39 | }
40 |
41 | it('should resolve extended modules variables in import default', () => {
42 | const src = [
43 | 'import testComponent from "./testComponent"',
44 | 'export default {',
45 | ' extends:testComponent',
46 | '}',
47 | ].join('\n')
48 | parseItExtends(src)
49 | expect(parseFile).toHaveBeenCalledWith(doc, {
50 | filePath: './component/full/path',
51 | nameFilter: ['default'],
52 | })
53 | })
54 |
55 | it('should resolve extended modules variables in require', () => {
56 | const src = [
57 | 'const testComponent = require("./testComponent");',
58 | 'export default {',
59 | ' extends:testComponent',
60 | '}',
61 | ].join('\n')
62 | parseItExtends(src)
63 | expect(parseFile).toHaveBeenCalledWith(doc, {
64 | filePath: './component/full/path',
65 | nameFilter: ['default'],
66 | })
67 | })
68 |
69 | it('should resolve extended modules variables in import', () => {
70 | const src = [
71 | 'import { test as testComponent, other } from "./testComponent"',
72 | 'export default {',
73 | ' extends:testComponent',
74 | '}',
75 | ].join('\n')
76 | parseItExtends(src)
77 | expect(parseFile).toHaveBeenCalledWith(doc, {
78 | filePath: './component/full/path',
79 | nameFilter: ['default'],
80 | })
81 | })
82 |
83 | it('should resolve extended modules variables in class style components', () => {
84 | const src = [
85 | 'import { testComponent } from "./testComponent";',
86 | '@Component',
87 | 'export default class Bart extends testComponent {',
88 | '}',
89 | ].join('\n')
90 | parseItExtends(src)
91 | expect(parseFile).toHaveBeenCalledWith(doc, {
92 | filePath: './component/full/path',
93 | nameFilter: ['default'],
94 | })
95 | })
96 | })
97 |
--------------------------------------------------------------------------------
/src/template-handlers/propHandler.ts:
--------------------------------------------------------------------------------
1 | import * as bt from '@babel/types'
2 | import recast from 'recast'
3 | import { ASTElement, ASTExpression, ASTNode } from 'vue-template-compiler'
4 | import buildParser from '../babel-parser'
5 | import { Documentation, ParamTag } from '../Documentation'
6 | import { TemplateParserOptions } from '../parse-template'
7 | import extractLeadingComment from '../utils/extractLeadingComment'
8 | import getDoclets from '../utils/getDoclets'
9 |
10 | const parser = buildParser({ plugins: ['typescript'] })
11 |
12 | const allowRE = /^(v-bind|:)/
13 | export default function propTemplateHandler(
14 | documentation: Documentation,
15 | templateAst: ASTElement,
16 | options: TemplateParserOptions,
17 | ) {
18 | if (options.functional) {
19 | propsInAttributes(templateAst, documentation, options)
20 | propsInInterpolation(templateAst, documentation, options)
21 | }
22 | }
23 |
24 | function propsInAttributes(
25 | templateAst: ASTElement,
26 | documentation: Documentation,
27 | options: TemplateParserOptions,
28 | ) {
29 | const bindings = templateAst.attrsMap
30 | const keys = Object.keys(bindings)
31 | for (const key of keys) {
32 | // only look at expressions
33 | if (allowRE.test(key)) {
34 | const expression = bindings[key]
35 | getPropsFromExpression(templateAst.parent, templateAst, expression, documentation, options)
36 | }
37 | }
38 | }
39 |
40 | function propsInInterpolation(
41 | templateAst: ASTElement,
42 | documentation: Documentation,
43 | options: TemplateParserOptions,
44 | ) {
45 | if (templateAst.children) {
46 | templateAst.children
47 | .filter(c => c.type === 2)
48 | .forEach((expr: ASTExpression) => {
49 | getPropsFromExpression(templateAst, expr, expr.expression, documentation, options)
50 | })
51 | }
52 | }
53 |
54 | function getPropsFromExpression(
55 | parentAst: ASTElement | undefined,
56 | item: ASTNode,
57 | expression: string,
58 | documentation: Documentation,
59 | options: TemplateParserOptions,
60 | ) {
61 | const ast = parser.parse(expression)
62 | const propsFound: string[] = []
63 | recast.visit(ast.program, {
64 | visitMemberExpression(path) {
65 | const obj = path.node ? path.node.object : undefined
66 | const propName = path.node ? path.node.property : undefined
67 | if (
68 | obj &&
69 | propName &&
70 | bt.isIdentifier(obj) &&
71 | obj.name === 'props' &&
72 | bt.isIdentifier(propName)
73 | ) {
74 | const pName = propName.name
75 | const p = documentation.getPropDescriptor(pName)
76 | propsFound.push(pName)
77 | p.type = { name: 'undefined' }
78 | }
79 | return false
80 | },
81 | })
82 | if (propsFound.length) {
83 | const comment = extractLeadingComment(parentAst, item, options.rootLeadingComment)
84 | const doclets = getDoclets(comment)
85 | const propTags = doclets.tags && (doclets.tags.filter(d => d.title === 'prop') as ParamTag[])
86 | if (propTags && propTags.length) {
87 | propsFound.forEach(pName => {
88 | const propTag = propTags.filter(pt => pt.name === pName)
89 | if (propTag.length) {
90 | const p = documentation.getPropDescriptor(pName)
91 | p.type = propTag[0].type
92 | if (typeof propTag[0].description === 'string') {
93 | p.description = propTag[0].description
94 | }
95 | }
96 | })
97 | }
98 | }
99 | }
100 |
--------------------------------------------------------------------------------
/src/utils/resolveRequired.ts:
--------------------------------------------------------------------------------
1 | import * as bt from '@babel/types'
2 | import { NodePath } from 'ast-types'
3 | import recast from 'recast'
4 |
5 | interface ImportedVariable {
6 | filePath: string
7 | exportName: string
8 | }
9 |
10 | export interface ImportedVariableSet {
11 | [key: string]: ImportedVariable
12 | }
13 |
14 | /**
15 | *
16 | * @param ast
17 | * @param varNameFilter
18 | */
19 | export default function resolveRequired(
20 | ast: bt.File,
21 | varNameFilter?: string[],
22 | ): ImportedVariableSet {
23 | const varToFilePath: ImportedVariableSet = {}
24 |
25 | recast.visit(ast.program, {
26 | visitImportDeclaration(astPath: NodePath) {
27 | const specifiers = astPath.get('specifiers')
28 |
29 | // if `import 'module'` without variable name cannot be a mixin
30 | specifiers.each((sp: NodePath) => {
31 | const nodeSpecifier = sp.node
32 | if (bt.isImportDefaultSpecifier(nodeSpecifier) || bt.isImportSpecifier(nodeSpecifier)) {
33 | const localVariableName = nodeSpecifier.local.name
34 |
35 | const exportName = bt.isImportDefaultSpecifier(nodeSpecifier)
36 | ? 'default'
37 | : nodeSpecifier.imported.name
38 |
39 | if (!varNameFilter || varNameFilter.indexOf(localVariableName) > -1) {
40 | const nodeSource = (astPath.get('source') as NodePath).node
41 | if (bt.isStringLiteral(nodeSource)) {
42 | const filePath = nodeSource.value
43 | varToFilePath[localVariableName] = {
44 | filePath,
45 | exportName,
46 | }
47 | }
48 | }
49 | }
50 | })
51 | return false
52 | },
53 |
54 | visitVariableDeclaration(astPath: NodePath) {
55 | // only look at variable declarations
56 | if (!bt.isVariableDeclaration(astPath.node)) {
57 | return false
58 | }
59 | astPath.node.declarations.forEach(nodeDeclaration => {
60 | let sourceNode: bt.Node
61 | let source: string = ''
62 |
63 | const { init, exportName } =
64 | nodeDeclaration.init && bt.isMemberExpression(nodeDeclaration.init)
65 | ? {
66 | init: nodeDeclaration.init.object,
67 | exportName: bt.isIdentifier(nodeDeclaration.init.property)
68 | ? nodeDeclaration.init.property.name
69 | : 'default',
70 | }
71 | : { init: nodeDeclaration.init, exportName: 'default' }
72 | if (!init) {
73 | return
74 | }
75 |
76 | if (bt.isCallExpression(init)) {
77 | if (!bt.isIdentifier(init.callee) || init.callee.name !== 'require') {
78 | return
79 | }
80 | sourceNode = init.arguments[0]
81 | if (!bt.isStringLiteral(sourceNode)) {
82 | return
83 | }
84 | source = sourceNode.value
85 | } else {
86 | return
87 | }
88 |
89 | if (bt.isIdentifier(nodeDeclaration.id)) {
90 | const varName = nodeDeclaration.id.name
91 | varToFilePath[varName] = { filePath: source, exportName }
92 | } else if (bt.isObjectPattern(nodeDeclaration.id)) {
93 | nodeDeclaration.id.properties.forEach((p: bt.ObjectProperty) => {
94 | const varName = p.key.name
95 | varToFilePath[varName] = { filePath: source, exportName }
96 | })
97 | } else {
98 | return
99 | }
100 | })
101 | return false
102 | },
103 | })
104 |
105 | return varToFilePath
106 | }
107 |
--------------------------------------------------------------------------------
/tests/components/button/Button.vue:
--------------------------------------------------------------------------------
1 |
2 |
3 |
7 |
8 |
9 |
138 |
139 |
151 |
--------------------------------------------------------------------------------
/src/script-handlers/__tests__/slotHandler.ts:
--------------------------------------------------------------------------------
1 | import { NodePath } from 'ast-types'
2 | import babylon from '../../babel-parser'
3 | import { Documentation, SlotDescriptor } from '../../Documentation'
4 | import resolveExportedComponent from '../../utils/resolveExportedComponent'
5 | import slotHandler from '../slotHandler'
6 |
7 | jest.mock('../../Documentation')
8 |
9 | function parse(src: string): NodePath | undefined {
10 | const ast = babylon().parse(src)
11 | return resolveExportedComponent(ast).get('default')
12 | }
13 |
14 | describe('render function slotHandler', () => {
15 | let documentation: Documentation
16 | let mockSlotDescriptor: SlotDescriptor
17 |
18 | beforeEach(() => {
19 | mockSlotDescriptor = { description: '' }
20 | documentation = new Documentation()
21 | const mockGetSlotDescriptor = documentation.getSlotDescriptor as jest.Mock
22 | mockGetSlotDescriptor.mockReturnValue(mockSlotDescriptor)
23 | })
24 |
25 | it('should find slots in render function', () => {
26 | const src = `
27 | export default {
28 | render: function (createElement) {
29 | return createElement('div', this.$slots.mySlot)
30 | }
31 | }
32 | `
33 | const def = parse(src)
34 | if (def) {
35 | slotHandler(documentation, def)
36 | }
37 | expect(documentation.getSlotDescriptor).toHaveBeenCalledWith('mySlot')
38 | })
39 |
40 | it('should find scoped slots in render function', () => {
41 | const src = `
42 | export default {
43 | render: function (createElement) {
44 | return createElement('div', [
45 | this.$scopedSlots.myScopedSlot({
46 | text: this.message
47 | })
48 | ])
49 | }
50 | }
51 | `
52 | const def = parse(src)
53 | if (def) {
54 | slotHandler(documentation, def)
55 | }
56 | expect(documentation.getSlotDescriptor).toHaveBeenCalledWith('myScopedSlot')
57 | })
58 |
59 | it('should find scoped slots in render object method', () => {
60 | const src = `
61 | export default {
62 | render(createElement) {
63 | return createElement('div', [
64 | this.$scopedSlots.myOtherScopedSlot({
65 | text: this.message
66 | })
67 | ])
68 | }
69 | }
70 | `
71 | const def = parse(src)
72 | if (def) {
73 | slotHandler(documentation, def)
74 | }
75 | expect(documentation.getSlotDescriptor).toHaveBeenCalledWith('myOtherScopedSlot')
76 | })
77 |
78 | it('should find slots in jsx render', () => {
79 | const src = `
80 | export default {
81 | render(createElement) {
82 | return (,
83 |
84 |
)
85 | }
86 | }
87 | `
88 | const def = parse(src)
89 | if (def) {
90 | slotHandler(documentation, def)
91 | }
92 | expect(documentation.getSlotDescriptor).toHaveBeenCalledWith('myMain')
93 | })
94 |
95 | it('should find default slots in jsx render', () => {
96 | const src = `
97 | export default {
98 | render(createElement) {
99 | return (,
100 |
101 |
)
102 | }
103 | }
104 | `
105 | const def = parse(src)
106 | if (def) {
107 | slotHandler(documentation, def)
108 | }
109 | expect(documentation.getSlotDescriptor).toHaveBeenCalledWith('default')
110 | })
111 |
112 | it('should allow describing slots in jsx render', () => {
113 | const src = `
114 | export default {
115 | render(createElement) {
116 | return (,
117 | {/** @slot Use this slot header */}
118 |
119 |
)
120 | }
121 | }
122 | `
123 | const def = parse(src)
124 | if (def) {
125 | slotHandler(documentation, def)
126 | }
127 | expect(mockSlotDescriptor.description).toEqual('Use this slot header')
128 | })
129 | })
130 |
--------------------------------------------------------------------------------
/src/script-handlers/__tests__/classPropHandler.ts:
--------------------------------------------------------------------------------
1 | import { NodePath } from 'ast-types'
2 | import Map from 'ts-map'
3 | import babylon from '../../babel-parser'
4 | import { Documentation, PropDescriptor } from '../../Documentation'
5 | import resolveExportedComponent from '../../utils/resolveExportedComponent'
6 | import classPropHandler from '../classPropHandler'
7 |
8 | jest.mock('../../Documentation')
9 |
10 | function parse(src: string): Map {
11 | const ast = babylon({ plugins: ['typescript'] }).parse(src)
12 | return resolveExportedComponent(ast)
13 | }
14 |
15 | describe('propHandler', () => {
16 | let documentation: Documentation
17 | let mockPropDescriptor: PropDescriptor
18 |
19 | beforeEach(() => {
20 | mockPropDescriptor = {
21 | description: '',
22 | required: '',
23 | tags: {},
24 | }
25 | const MockDocumentation = require('../../Documentation').Documentation
26 | documentation = new MockDocumentation()
27 | const mockGetPropDescriptor = documentation.getPropDescriptor as jest.Mock
28 | mockGetPropDescriptor.mockReturnValue(mockPropDescriptor)
29 | })
30 |
31 | function tester(src: string, matchedObj: any) {
32 | const def = parse(src).get('default')
33 | classPropHandler(documentation, def as any)
34 | expect(mockPropDescriptor).toMatchObject(matchedObj)
35 | }
36 |
37 | describe('base', () => {
38 | it('should ignore data that does not have the prop decorator', () => {
39 | const src = `
40 | @Component
41 | export default class MyComp {
42 | someData: boolean;
43 | }`
44 | tester(src, {})
45 | expect(documentation.getPropDescriptor).not.toHaveBeenCalledWith('someData')
46 | })
47 | it('should detect all data that have the prop decorator', () => {
48 | const src = `
49 | @Component
50 | export default class MyComp {
51 | @Prop
52 | test: string;
53 | }`
54 | tester(src, {
55 | type: { name: 'string' },
56 | })
57 | expect(documentation.getPropDescriptor).toHaveBeenCalledWith('test')
58 | })
59 |
60 | it('should get default expression from the prop decorator', () => {
61 | const src = `
62 | @Component
63 | export default class MyTest {
64 | @Prop({default: 'hello'})
65 | testDefault: string;
66 | }`
67 | tester(src, {
68 | type: { name: 'string' },
69 | defaultValue: {
70 | value: `"hello"`,
71 | },
72 | })
73 | expect(documentation.getPropDescriptor).toHaveBeenCalledWith('testDefault')
74 | })
75 |
76 | it('should get required from the prop decorator', () => {
77 | const src = `
78 | @Component
79 | export default class MyTest {
80 | @Prop({required: true})
81 | testRequired: string;
82 | }`
83 | tester(src, {
84 | type: { name: 'string' },
85 | required: true,
86 | })
87 | expect(documentation.getPropDescriptor).toHaveBeenCalledWith('testRequired')
88 | })
89 |
90 | it('should extract descriptions from leading comments', () => {
91 | const src = `
92 | @Component
93 | export default class MyTest {
94 | /**
95 | * A described prop
96 | **/
97 | @Prop
98 | testDescribed: boolean;
99 | }`
100 | tester(src, {
101 | description: 'A described prop',
102 | })
103 | expect(documentation.getPropDescriptor).toHaveBeenCalledWith('testDescribed')
104 | })
105 |
106 | it('should extract type from decorator arguments', () => {
107 | const src = `
108 | @Component
109 | export default class MyTest {
110 | @Prop({type:String})
111 | testTyped;
112 | }`
113 | tester(src, {
114 | type: { name: 'string' },
115 | })
116 | expect(documentation.getPropDescriptor).toHaveBeenCalledWith('testTyped')
117 | })
118 | })
119 | })
120 |
--------------------------------------------------------------------------------
/src/script-handlers/__tests__/eventHandler.ts:
--------------------------------------------------------------------------------
1 | import * as bt from '@babel/types'
2 | import { NodePath } from 'ast-types'
3 | import babylon from '../../babel-parser'
4 | import { Documentation, EventDescriptor } from '../../Documentation'
5 | import resolveExportedComponent from '../../utils/resolveExportedComponent'
6 | import eventHandler from '../eventHandler'
7 |
8 | jest.mock('../../Documentation')
9 |
10 | function parse(src: string): { component: NodePath | undefined; ast: bt.File } {
11 | const ast = babylon().parse(src)
12 | return { component: resolveExportedComponent(ast).get('default'), ast }
13 | }
14 |
15 | describe('eventHandler', () => {
16 | let documentation: Documentation
17 | let mockEventDescriptor: EventDescriptor
18 |
19 | beforeEach(() => {
20 | mockEventDescriptor = { description: '', properties: [] }
21 | documentation = new (require('../../Documentation')).Documentation()
22 | const mockGetEventDescriptor = documentation.getEventDescriptor as jest.Mock
23 | mockGetEventDescriptor.mockReturnValue(mockEventDescriptor)
24 | })
25 |
26 | it('should find events emmitted', () => {
27 | const src = `
28 | export default {
29 | methods: {
30 | testEmit() {
31 | /**
32 | * Describe the event
33 | * @property {number} prop1
34 | * @property {number} prop2
35 | */
36 | this.$emit('success', 1, 2)
37 | }
38 | }
39 | }
40 | `
41 | const def = parse(src)
42 | if (def.component) {
43 | eventHandler(documentation, def.component, def.ast)
44 | }
45 | const eventComp: EventDescriptor = {
46 | description: 'Describe the event',
47 | properties: [
48 | {
49 | name: 'prop1',
50 | type: {
51 | names: ['number'],
52 | },
53 | },
54 | {
55 | name: 'prop2',
56 | type: {
57 | names: ['number'],
58 | },
59 | },
60 | ],
61 | }
62 | expect(documentation.getEventDescriptor).toHaveBeenCalledWith('success')
63 | expect(mockEventDescriptor).toMatchObject(eventComp)
64 | })
65 |
66 | it('should find events undocumented properties', () => {
67 | const src = `
68 | export default {
69 | methods: {
70 | testEmit() {
71 | this.$emit('success', 1, 2)
72 | }
73 | }
74 | }
75 | `
76 | const def = parse(src)
77 | if (def.component) {
78 | eventHandler(documentation, def.component, def.ast)
79 | }
80 | const eventComp: EventDescriptor = {
81 | description: '',
82 | type: {
83 | names: ['undefined'],
84 | },
85 | properties: [
86 | {
87 | name: '',
88 | type: {
89 | names: ['undefined'],
90 | },
91 | },
92 | ],
93 | }
94 | expect(documentation.getEventDescriptor).toHaveBeenCalledWith('success')
95 | expect(mockEventDescriptor).toMatchObject(eventComp)
96 | })
97 |
98 | it('should find events names stored in variables', () => {
99 | const src = `
100 | const successEventName = 'success';
101 | export default {
102 | methods: {
103 | testEmit() {
104 | this.$emit(successEventName, 1, 2)
105 | }
106 | }
107 | }
108 | `
109 | const def = parse(src)
110 | if (def.component) {
111 | eventHandler(documentation, def.component, def.ast)
112 | }
113 | expect(documentation.getEventDescriptor).toHaveBeenCalledWith('success')
114 | })
115 |
116 | it('should find events whose names are only spcified in the JSDoc', () => {
117 | const src = `
118 | export default {
119 | methods: {
120 | testEmit() {
121 | /**
122 | * @event success
123 | */
124 | this.$emit(A.successEventName, 1, 2)
125 | }
126 | }
127 | }
128 | `
129 | const def = parse(src)
130 | if (def.component) {
131 | eventHandler(documentation, def.component, def.ast)
132 | }
133 | expect(documentation.getEventDescriptor).toHaveBeenCalledWith('success')
134 | })
135 | })
136 |
--------------------------------------------------------------------------------
/tests/components/grid-jsx/grid-jsx.test.ts:
--------------------------------------------------------------------------------
1 | import * as path from 'path'
2 | import { ComponentDoc, PropDescriptor } from '../../../src/Documentation'
3 | import { parse } from '../../../src/main'
4 |
5 | const grid = path.join(__dirname, './Grid.vue')
6 | let docGrid: ComponentDoc
7 |
8 | describe('tests grid jsx', () => {
9 | beforeAll(done => {
10 | docGrid = parse(grid)
11 | done()
12 | })
13 |
14 | it('should return an object', () => {
15 | expect(typeof docGrid).toBe('object')
16 | })
17 |
18 | it('The component name should be grid', () => {
19 | expect(docGrid.displayName).toEqual('grid')
20 | })
21 |
22 | it('should the component has tags', () => {
23 | expect(typeof docGrid.tags !== 'undefined').toBe(true)
24 | })
25 |
26 | it('should the component has authors', () => {
27 | expect(typeof docGrid.tags.author !== 'undefined').toBe(true)
28 | })
29 |
30 | it('should the component has description', () => {
31 | expect(typeof docGrid.description !== 'undefined').toBe(true)
32 | })
33 |
34 | it('should has methods', () => {
35 | expect(typeof docGrid.methods !== 'undefined').toBe(true)
36 | })
37 |
38 | it('should the component has one method', () => {
39 | expect(Object.keys(docGrid.methods).length).toEqual(1)
40 | })
41 |
42 | it('should has props', () => {
43 | expect(docGrid.props).not.toBeUndefined()
44 | })
45 |
46 | it('should the component has version', () => {
47 | expect(typeof docGrid.tags.version !== 'undefined').toBe(true)
48 | })
49 | describe('props', () => {
50 | let props: { [propName: string]: PropDescriptor }
51 |
52 | beforeAll(() => {
53 | props = docGrid.props ? docGrid.props : {}
54 | })
55 | it('should the component has four props', () => {
56 | expect(Object.keys(props).length).toEqual(6)
57 | })
58 |
59 | it('grid component should have a msg prop as string|number type', () => {
60 | expect(props.msg.type).toMatchObject({ name: 'string|number' })
61 | })
62 |
63 | it('grid component should have a filterKey prop as string type', () => {
64 | expect(props.filterKey.type).toMatchObject({ name: 'string' })
65 | })
66 |
67 | it('grid component should have a propFunc prop as func type', () => {
68 | expect(props.propFunc.type).toMatchObject({ name: 'func' })
69 | })
70 |
71 | it('grid component should have a images prop as Array type', () => {
72 | expect(props.images.type).toMatchObject({ name: 'array' })
73 | })
74 |
75 | it('grid component should have a data prop as Array type', () => {
76 | expect(props.data.type).toMatchObject({ name: 'array' })
77 | })
78 |
79 | it('grid component should have a columns prop as Array type', () => {
80 | expect(props.columns.type).toMatchObject({ name: 'array' })
81 | })
82 |
83 | it('should the prop msg has four tags', () => {
84 | expect(Object.keys(props.msg.tags).length).toEqual(4)
85 | })
86 | })
87 |
88 | it('should the component has two event', () => {
89 | expect(Object.keys(docGrid.events || {}).length).toEqual(2)
90 | })
91 |
92 | it('should the component has event, it called success', () => {
93 | expect(typeof (docGrid.events || {}).success !== 'undefined').toBe(true)
94 | })
95 |
96 | it('should the description of success event is Success event.', () => {
97 | expect((docGrid.events || {}).success.description).toEqual('Success event.')
98 | })
99 |
100 | it('should the component has event, it called error', () => {
101 | expect(typeof (docGrid.events || {}).error !== 'undefined').toBe(true)
102 | })
103 |
104 | it('should the description of error event is Error event.', () => {
105 | expect((docGrid.events || {}).error.description).toEqual('Error event.')
106 | })
107 |
108 | it('should define the return type of the first method', () => {
109 | expect(docGrid.methods[0].returns).toMatchObject({ description: 'Test' })
110 | })
111 |
112 | it('should return slots from the render method', () => {
113 | expect(docGrid.slots.header).toMatchObject({ description: 'Use this slot header' })
114 | })
115 |
116 | it('should match the snapshot', () => {
117 | expect(docGrid).toMatchSnapshot()
118 | })
119 | })
120 |
--------------------------------------------------------------------------------
/src/script-handlers/eventHandler.ts:
--------------------------------------------------------------------------------
1 | import * as bt from '@babel/types'
2 | import { NodePath } from 'ast-types'
3 | import recast from 'recast'
4 | import {
5 | BlockTag,
6 | DocBlockTags,
7 | Documentation,
8 | EventDescriptor,
9 | ParamTag,
10 | ParamType,
11 | Tag,
12 | } from '../Documentation'
13 | import getDocblock from '../utils/getDocblock'
14 | import getDoclets from '../utils/getDoclets'
15 | import resolveIdentifier from '../utils/resolveIdentifier'
16 |
17 | export interface TypedParamTag extends ParamTag {
18 | type: ParamType
19 | }
20 |
21 | export default function eventHandler(
22 | documentation: Documentation,
23 | path: NodePath,
24 | astPath: bt.File,
25 | ) {
26 | recast.visit(path.node, {
27 | visitCallExpression(pathExpression) {
28 | if (
29 | bt.isMemberExpression(pathExpression.node.callee) &&
30 | bt.isThisExpression(pathExpression.node.callee.object) &&
31 | bt.isIdentifier(pathExpression.node.callee.property) &&
32 | pathExpression.node.callee.property.name === '$emit'
33 | ) {
34 | const args = pathExpression.node.arguments
35 | if (!args.length) {
36 | return false
37 | }
38 | // fetch the leading comments on the wrapping expression
39 | const docblock = getDocblock(pathExpression.parentPath)
40 | const doclets = getDoclets(docblock || '')
41 | let eventName: string
42 | const eventTags = doclets.tags ? doclets.tags.filter(d => d.title === 'event') : []
43 |
44 | // if someone wants to document it with anything else, they can force it
45 | if (eventTags.length) {
46 | eventName = (eventTags[0] as Tag).content as string
47 | } else {
48 | let firstArg = pathExpression.get('arguments', 0)
49 | if (bt.isIdentifier(firstArg.node)) {
50 | firstArg = resolveIdentifier(astPath, firstArg)
51 | }
52 |
53 | if (!bt.isStringLiteral(firstArg.node)) {
54 | return false
55 | }
56 | eventName = firstArg.node.value
57 | }
58 |
59 | // if this event is documented somewhere else leave it alone
60 | const evtDescriptor = documentation.getEventDescriptor(eventName)
61 |
62 | setEventDescriptor(evtDescriptor, doclets)
63 |
64 | if (args.length > 1 && !evtDescriptor.type) {
65 | evtDescriptor.type = {
66 | names: ['undefined'],
67 | }
68 | }
69 |
70 | if (args.length > 2 && !evtDescriptor.properties) {
71 | evtDescriptor.properties = []
72 | }
73 | if (evtDescriptor.properties && evtDescriptor.properties.length < args.length - 2) {
74 | let i = args.length - 2 - evtDescriptor.properties.length
75 | while (i--) {
76 | evtDescriptor.properties.push({
77 | type: { names: ['undefined'] },
78 | name: ``,
79 | })
80 | }
81 | }
82 | return false
83 | }
84 | this.traverse(pathExpression)
85 | },
86 | })
87 | }
88 |
89 | export function setEventDescriptor(
90 | eventDescriptor: EventDescriptor,
91 | jsDoc: DocBlockTags,
92 | ): EventDescriptor {
93 | eventDescriptor.description = jsDoc.description || ''
94 |
95 | const nonNullTags: BlockTag[] = jsDoc.tags ? jsDoc.tags : []
96 |
97 | const typeTags = nonNullTags.filter(tg => tg.title === 'type')
98 | eventDescriptor.type = typeTags.length
99 | ? { names: typeTags.map((t: TypedParamTag) => t.type.name) }
100 | : undefined
101 |
102 | const propertyTags = nonNullTags.filter(tg => tg.title === 'property')
103 | if (propertyTags.length) {
104 | eventDescriptor.properties = propertyTags.map((tg: TypedParamTag) => {
105 | return { type: { names: [tg.type.name] }, name: tg.name, description: tg.description }
106 | })
107 | }
108 |
109 | // remove the property an type tags from the tag array
110 | const tags = nonNullTags.filter(
111 | (tg: BlockTag) => tg.title !== 'type' && tg.title !== 'property' && tg.title !== 'event',
112 | )
113 |
114 | if (tags.length) {
115 | eventDescriptor.tags = tags
116 | } else {
117 | delete eventDescriptor.tags
118 | }
119 |
120 | return eventDescriptor
121 | }
122 |
--------------------------------------------------------------------------------
/tests/components/grid-jsx/Grid.vue:
--------------------------------------------------------------------------------
1 |
2 |
157 |
158 |
163 |
--------------------------------------------------------------------------------
/tests/components/grid/Grid.vue:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 | |
9 | {{ key | capitalize }}
10 |
11 | |
12 |
13 |
14 |
15 |
16 | | {{entry[key]}} |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
3 |
4 |
5 |
6 |
7 |
8 | |
9 | {{ key | capitalize }}
10 |
11 | |
12 |
13 |
14 |
15 |
16 | | {{entry[key]}} |
17 |
18 |
19 |
20 |
21 |
22 |
23 |