JSDoc 单文件 Vue 组件答案

【问题标题】：JSDoc single file Vue componentsJSDoc 单文件 Vue 组件
【发布时间】：2017-08-07 08:40:10
【问题描述】：

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

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

和

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

使用速记时插件会中断，但这不是什么大问题，我可以使用速记。但是，我尝试在其上运行 JSDoc 的每个文件组件都会出现此错误：

相邻的 JSX 元素必须包含在封闭标签中

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

<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 文件上运行 JSDoc 的经验？好像应该可以，但是网上资料太少了。

谢谢

【问题讨论】：

你设置了你的 conf.json 吗？
我们正在使用这个方便的文档生成器。也许它适合你。 github.com/vue-styleguidist/vue-styleguidist
截至2020年，jsdoc-vue没有OP报告的问题，使用起来相当简单。

标签： vue.js jsdoc

【解决方案1】：

我一直在使用 documentation.js 来记录我的 Vue 文件。 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 更进一步，允许您将文档添加到您的道具和组件中。它非常易于使用。

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

【讨论】：

太棒了！但是我在处理 pug 时遇到了问题（错误：解析文件 /path/to/file.vue: Unexpected token (1:0) My file.vue start with
@DmytroLishtvan 嗯...我没有玩太多 Pug 并且根本没有使用 Vue。我的猜测是 documentation.js 是专门为解析 HTML/JS 文件而构建的，如果我错了，请有人纠正我。查看我上面关于 vuese 的编辑，我猜它应该可以很好地与 Pug 模板一起使用。
@Brett Fisher 你好！使用 vuese-parser 修改 vuese 生成的文档我运气不佳。大多数情况下，我只是想为我的方法添加一个“返回”列。你有没有机会指出我正确的方向或提供一个例子？

【解决方案2】：

我写了一个简单的@component 插件，它可以帮助用@jsdoc 解析.vue 文件。它还为它们生成预览。看看吧：https://github.com/SoftwareBrothers/better-docs

【讨论】：