feat: extract type and description of functional props

closes #86

Author: elevatebart

src/template-handlers/__tests__/propHandler.ts

@@ -14,14 +14,19 @@ describe('slotHandler', () => {
       [
         '<div>',
         '  <h1>titleof the template</h1>',
-        '  <button :style="`width:${props.size}`"></button>',
+        '  <!-- @prop {number} size width of the button -->',
+        '  <!-- @prop {string} value value in the form -->',
+        '  <button :style="`width:${props.size}`" :value="props.value"></button>',
         '</div>',
       ].join('\n'),
       { comments: true },
     ).ast
     if (ast) {
       traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
-      expect(doc.toObject().props).toMatchObject({ size: { type: { name: 'undefined' } } })
+      expect(doc.toObject().props).toMatchObject({
+        size: { type: { name: 'number' }, description: 'width of the button' },
+        value: { type: { name: 'string' }, description: 'value in the form' },
+      })
     } else {
       fail()
     }
@@ -33,15 +38,20 @@ describe('slotHandler', () => {
         '<div>',
         '  <h1>titleof the template</h1>',
         '  <button style="width:200px">',
-        '    test {{props.name}}',
+        '    <!-- @prop name Your Name -->',
+        '    <!-- @prop {string} adress Your Adress -->',
+        '    test {{props.name}} {{props.adress}}',
         '  </button>',
         '</div>',
       ].join('\n'),
       { comments: true },
     ).ast
     if (ast) {
       traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
-      expect(doc.toObject().props).toMatchObject({ name: { type: { name: 'undefined' } } })
+      expect(doc.toObject().props).toMatchObject({
+        name: { type: { name: 'mixed' }, description: 'Your Name' },
+        adress: { type: { name: 'string' }, description: 'Your Adress' },
+      })
     } else {
       fail()
     }

src/template-handlers/propHandler.ts

@@ -1,9 +1,13 @@
 import * as bt from '@babel/types'
 import recast from 'recast'
-import { ASTElement, ASTExpression } from 'vue-template-compiler'
+import { ASTElement, ASTExpression, ASTNode } from 'vue-template-compiler'
 import buildParser from '../babel-parser'
-import { Documentation } from '../Documentation'
+import { Documentation, ParamTag } from '../Documentation'
 import { TemplateParserOptions } from '../parse-template'
+import extractLeadingComment from '../utils/extractLeadingComment'
+import getDoclets from '../utils/getDoclets'
+
+const parser = buildParser({ plugins: ['typescript'] })
 
 const allowRE = /^(v-bind|:)/
 export default function propTemplateHandler(
@@ -12,35 +16,50 @@ export default function propTemplateHandler(
   options: TemplateParserOptions,
 ) {
   if (options.functional) {
-    propsInAttributes(templateAst, documentation)
-    propsInInterpolation(templateAst, documentation)
+    propsInAttributes(templateAst, documentation, options)
+    propsInInterpolation(templateAst, documentation, options)
   }
 }
 
-function propsInAttributes(templateAst: ASTElement, documentation: Documentation) {
+function propsInAttributes(
+  templateAst: ASTElement,
+  documentation: Documentation,
+  options: TemplateParserOptions,
+) {
   const bindings = templateAst.attrsMap
   const keys = Object.keys(bindings)
   for (const key of keys) {
     // only look at expressions
     if (allowRE.test(key)) {
       const expression = bindings[key]
-      getPropsFromExpression(expression, documentation)
+      getPropsFromExpression(templateAst.parent, templateAst, expression, documentation, options)
     }
   }
 }
 
-function propsInInterpolation(templateAst: ASTElement, documentation: Documentation) {
+function propsInInterpolation(
+  templateAst: ASTElement,
+  documentation: Documentation,
+  options: TemplateParserOptions,
+) {
   if (templateAst.children) {
     templateAst.children
       .filter(c => c.type === 2)
       .forEach((expr: ASTExpression) => {
-        getPropsFromExpression(expr.expression, documentation)
+        getPropsFromExpression(templateAst, expr, expr.expression, documentation, options)
       })
   }
 }
 
-function getPropsFromExpression(expression: string, documentation: Documentation) {
-  const ast = buildParser({ plugins: ['typescript'] }).parse(expression)
+function getPropsFromExpression(
+  parentAst: ASTElement | undefined,
+  item: ASTNode,
+  expression: string,
+  documentation: Documentation,
+  options: TemplateParserOptions,
+) {
+  const ast = parser.parse(expression)
+  const propsFound: string[] = []
   recast.visit(ast.program, {
     visitMemberExpression(path) {
       const obj = path.node ? path.node.object : undefined
@@ -54,9 +73,27 @@ function getPropsFromExpression(expression: string, documentation: Documentation
       ) {
         const pName = propName.name
         const p = documentation.getPropDescriptor(pName)
+        propsFound.push(pName)
         p.type = { name: 'undefined' }
       }
       return false
     },
   })
+  if (propsFound.length) {
+    const comment = extractLeadingComment(parentAst, item, options.rootLeadingComment)
+    const doclets = getDoclets(comment)
+    const propTags = doclets.tags && (doclets.tags.filter(d => d.title === 'prop') as ParamTag[])
+    if (propTags && propTags.length) {
+      propsFound.forEach(pName => {
+        const propTag = propTags.filter(pt => pt.name === pName)
+        if (propTag.length) {
+          const p = documentation.getPropDescriptor(pName)
+          p.type = propTag[0].type
+          if (typeof propTag[0].description === 'string') {
+            p.description = propTag[0].description
+          }
+        }
+      })
+    }
+  }
 }

src/template-handlers/slotHandler.ts

@@ -1,6 +1,7 @@
-import { ASTElement, ASTNode } from 'vue-template-compiler'
+import { ASTElement } from 'vue-template-compiler'
 import { Documentation } from '../Documentation'
 import { TemplateParserOptions } from '../parse-template'
+import extractLeadingComment from '../utils/extractLeadingComment'
 
 export default function slotHandler(
   documentation: Documentation,
@@ -22,45 +23,12 @@ export default function slotHandler(
     }
 
     slotDescriptor.bindings = bindings
-    let comment = ''
-    if (templateAst.parent) {
-      const slotSiblings: ASTNode[] = templateAst.parent.children
-      // First find the position of the slot in the list
-      let i = slotSiblings.length - 1
-      let currentSlotIndex = -1
-      do {
-        if (slotSiblings[i] === templateAst) {
-          currentSlotIndex = i
-        }
-      } while (currentSlotIndex < 0 && i--)
-
-      // Find the first leading comment node as a description of the slot
-      const slotSiblingsBeforeSlot = slotSiblings.slice(0, currentSlotIndex).reverse()
-
-      for (const potentialComment of slotSiblingsBeforeSlot) {
-        // if there is text between the slot and the comment, ignore
-        if (
-          potentialComment.type !== 3 ||
-          (!potentialComment.isComment && potentialComment.text.trim())
-        ) {
-          break
-        }
-
-        if (
-          potentialComment.isComment &&
-          !(
-            templateAst.parent.tag === 'slot' && templateAst.parent.children[0] === potentialComment
-          )
-        ) {
-          comment = potentialComment.text.trim()
-
-          break
-        }
-      }
-    } else if (options.rootLeadingComment.length) {
-      comment = options.rootLeadingComment
-    }
 
+    const comment = extractLeadingComment(
+      templateAst.parent,
+      templateAst,
+      options.rootLeadingComment,
+    )
     if (comment.length && comment.search(/\@slot/) !== -1) {
       slotDescriptor.description = comment.replace('@slot', '').trim()
     }

src/utils/__tests__/extractLeadingComment.ts

@@ -0,0 +1,53 @@
+import extractLeadingComment from '../extractLeadingComment'
+import { ASTElement, compile } from 'vue-template-compiler'
+
+function compileIt(src: string): ASTElement | undefined {
+  const ast = compile(src, { comments: true }).ast
+  if (ast) {
+    const firstHeader = ast.children.filter((a: ASTElement) => a.tag === 'h1') as ASTElement[]
+    if (firstHeader.length) {
+      return firstHeader[0]
+    }
+  }
+  return ast
+}
+
+describe('extractLeadingComment', () => {
+  it('should extract single line comments', () => {
+    const elt = compileIt(
+      [
+        '<div>',
+        ' <div>Hello World !!</div>',
+        ' <div>Happy Day !!</div>',
+        ' <!-- single line comment -->',
+        ' <h1>title of the template</h1>',
+        '</div>',
+      ].join('\n'),
+    )
+    if (!elt) {
+      fail()
+    } else {
+      expect(extractLeadingComment(elt.parent, elt, '')).toBe('single line comment')
+    }
+  })
+
+  it('should extract multi line comments', () => {
+    const elt = compileIt(
+      [
+        '<div>',
+        '  <div>Hello World !!</div>',
+        '  <!-- multi line comment -->',
+        '  <!-- on 2 lines         -->',
+        '  <h1>title of the template</h1>',
+        '</div>',
+      ].join('\n'),
+    )
+    if (elt) {
+      expect(extractLeadingComment(elt.parent, elt, '')).toBe(
+        ['multi line comment', 'on 2 lines'].join('\n'),
+      )
+    } else {
+      fail()
+    }
+  })
+})

src/utils/extractLeadingComment.ts

@@ -0,0 +1,46 @@
+import { ASTElement, ASTNode } from 'vue-template-compiler'
+
+/**
+ * Extract leading comments to an html node
+ * Even if the comment is on multiple lines it's still taken as a whole
+ * @param templateAst
+ * @param rootLeadingComment
+ */
+export default function extractLeadingComment(
+  parentAst: ASTElement | undefined,
+  templateAst: ASTNode,
+  rootLeadingComment: string,
+): string {
+  let comment = ''
+  if (parentAst) {
+    const slotSiblings: ASTNode[] = parentAst.children
+    // First find the position of the slot in the list
+    let i = slotSiblings.length - 1
+    let currentSlotIndex = -1
+    do {
+      if (slotSiblings[i] === templateAst) {
+        currentSlotIndex = i
+      }
+    } while (currentSlotIndex < 0 && i--)
+
+    // Find the first leading comment
+    const slotSiblingsBeforeSlot = slotSiblings.slice(0, currentSlotIndex).reverse()
+
+    for (const potentialComment of slotSiblingsBeforeSlot) {
+      // if there is text between the slot and the comment, ignore
+      if (
+        potentialComment.type !== 3 ||
+        (!potentialComment.isComment && potentialComment.text.trim().length)
+      ) {
+        break
+      }
+
+      if (potentialComment.isComment) {
+        comment = potentialComment.text.trim() + '\n' + comment
+      }
+    }
+  } else if (rootLeadingComment.length) {
+    comment = rootLeadingComment
+  }
+  return comment.trim()
+}

src/utils/getDoclets.ts

@@ -45,7 +45,7 @@ function getTypeObjectFromTypeString(typeSlice: string): ParamType {
   }
 }
 
-const TYPED_TAG_TITLES = ['param', 'property', 'type', 'returns']
+const TYPED_TAG_TITLES = ['param', 'property', 'type', 'returns', 'prop']
 const ACCESS_TAG_TITLES = ['private', 'public']
 
 /**