ccqgithub / jsdoc-vue-component

A simple plugin for jsdoc (`pase vue SFC info to description`)

jsdoc-vue-component

A simple plugin for jsdoc (pase vue SFC info to description by AST analysis).

Maybe you will try jsdoc-vuedoc, and you have a better experience。

Installation

npm i jsdoc-vue-component -D

Related

• espree: parse code to ast.
• escodegen: generate code from ast.
• estraverse: traverse the AST tree.
• JsDoc3.
• docstrap: a theme for jsdoc3.
• jsdoc-vuedoc: A jsdoc3 plugin use @vuedoc/md.

Use:

This plugin just extract the component's info into markdown format, and instert it into the @vuedoc's position.

Not affect other jsdoc features of the code.

1. add @vuedoc tag to comment.
2. add @exports componentName tag to comment.

just add @vuedoc tag, @exports tag, to the to document in you vue SFC.

/**
 * sidebar component description
 * @vuedoc
 * @exports component/SideBar
 */
export default {}

如何使用jsdoc？

• 安装jsdoc: npm i jsdoc -D
• 安装模板：npm i sherry-docstrap -D, 原来的docstrap有点小bug还未修复，所以自己暂时发布一个。
• 在项目目录下建了配置文件：下面有示例，适当修改。
• 在pacakge.json 里添加一个script: "jsdoc": "rm -rf public/jsdoc && node_modules/.bin/jsdoc -c jsdoc.json", public/jsdoc为发布位置，适当修改
• 生成文档: npm run jsdoc

Options

• log: true,
• tag: 'vuedoc'

jsdoc.json

{
  "plugins": [
    "node_modules/jsdoc-vue-component",
    "plugins/markdown",
    "plugins/summarize"
  ],
  "jsdoc-vue-component": {
    "log": true
  },
  "markdown": {
    "tags": ["author", "classdesc", "description", "param", "property", "returns", "see", "throws", "vue"]
  },
  "recurseDepth": 10,
  "source": {
    "include": ["fe/src"],
    "includePattern": ".+\\.(js|vue)$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "sourceType": "module",
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "templates": {
    "logoFile": "",
    "cleverLinks": false,
    "monospaceLinks": false,
    "dateFormat": "ddd MMM Do YYYY",
    "outputSourceFiles": true,
    "outputSourcePath": true,
    "systemName": "DocStrap",
    "footer": "",
    "copyright": "DocStrap Copyright © 2012-2015 The contributors to the JSDoc3 and DocStrap projects.",
    "navType": "vertical",
    "theme": "cosmo",
    "linenums": true,
    "collapseSymbols": false,
    "inverseNav": true,
    "protocol": "html://",
    "methodHeadingReturns": false
  },
  "markdown": {
    "parser": "gfm",
    "hardwrap": true
  },
  "opts": {
    "template": "node_modules/sherry-docstrap/template",
    "encoding": "utf8",
    "destination": "./public/jsdoc/",
    "recurse": true,
    "readme": "README.md",
    "tutorials": "./docs/"
  }
}

效果

.

jsdoc-vue-component's Issues

vue组件的名称解析有误

// props: {}, object
if (item.value.type == 'ObjectExpression') {
item.value.properties.forEach(prop => {
// test: Type
if (prop.value.type == 'Identifier') {
props.push({
name: prop.key.name, // prop.key.name为undefined，改为prop.key.value即可
type: prop.value.name
});
}