JSDoc 单文件 Vue 组件

Question

我正在尝试运行 JSDoc 在我的单个文件 Vue 组件上。我发现了两个听起来应该可以工作的插件（实际上它们似乎都基于相同的代码）：

https://www.npmjs.com/package/vue-doc

和

https://www.npmjs.com/package/jsdoc-vue

当使用 shorthand 时插件会中断，但这不是什么大问题，我可以直接使用 longhand。但是，我尝试运行 JSDoc 的每个文件组件都会收到此错误：

Adjacent JSX elements must be wrapped in an enclosing tag

这意味着我的组件没有单个根元素，但它们都有。我像这样设置了一个测试组件，但它失败了：

<template>
  <div>
    {{someData}}
  </div>
</template>

<script>
  export default {
    data () {
      return {
        someData: "Test Data"
      }
    },
    methods: {
      /**
       * Just a test function
       * @function
       */
      testFunction: function () {
        alert("Testing")
      }
    }
  }
</script>

<style lang="stylus">
  div {
    border: 1px solid;
  }
</style>

有没有人有在 .vue 文件上使用运行ning JSDoc 的经验？好像应该可以，但是网上资料太少了

谢谢

Answer 1

我一直在使用 documentation.js to document my Vue files. Here's an excellent article 了解如何开始使用它。它的易用性给我留下了深刻的印象，它生成了美观的 HTML 文件，您可以使用这些文件轻松搜索您编写的函数。

例如，如果您创建这样一个 Vue 文件：

<template>
    <div>{{mydata}}</div>
</template>

<script>
export default {
    data: function() {
        return {
            mydata: "hello"
        }
    },
    methods: {
        /**
         * Add two numbers.
         * @param{number} num1 The first number to add
         * @param{number} num2 The second number to add
         * @return{number} The sum of the two numbers.
         */
        addnums: function(num1, num2) {
            return num1 + num2;
        },

        /**
         * Concatenate two strings.
         * @param{string} str1 The first string to concatenate.
         * @param{string} str2 The second string to concatenate.
         * @return{string} The concatentation of the two strings.
         */
        concat: function(str1, str2) {
            return str1 + str2;
        }
    }
}
</script>

运行 documentation build /path/to/file.vue -f html -o docs 将创建一个漂亮的 HTML 文件，在浏览器中看起来像这样：

2019 编辑：

实际上我昨天发现了一个名为 vuese 的新库，它是专门为记录 Vue 组件而构建的。虽然 documentation.js 可以很好地帮助您记录方法，但 vuese 更进一步，让您可以向 props 和组件添加文档。使用起来非常简单。

我几乎从 this blog post 那里学到了我需要知道的一切。

Answer 2

我写了一个简单的@component 插件，它有助于用@jsdoc 解析.vue 文件。它还为他们生成预览。检查一下：https://github.com/SoftwareBrothers/better-docs

JSDoc 单文件 Vue 组件

JSDoc single file Vue components

jsdoc

vue.js