JSDoc single file Vue components

Question

I'm trying to run JSDoc on my single file Vue components. I've found two plugins that sound like they should work (both seem to be based on the same code in fact):

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

and

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

The plugin breaks when shorthand is used, but that's not a big issue, I can just use longhand. However every single file component I try to run JSDoc on gets this error:

Adjacent JSX elements must be wrapped in an enclosing tag

This implies that my component doesn't have a single root element, but they all do. I set up a test component like so, but it fails:

<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>

Does anyone have any experience with running JSDoc on .vue files? It seems like it should be possible, but there's very little info online.

Thanks

Answer 1

I've been using documentation.js to document my Vue files. Here's an excellent article on how to get started using it. I've been very impressed with how easy it is to use, and it generates good looking HTML files that you can use to easily search for the functions you've written.

For example, if you create a Vue file like this:

<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>

Running documentation build /path/to/file.vue -f html -o docs will create a beautiful HTML file that looks like this in the browser:

2019 EDIT:

I actually found a new library yesterday called vuese that was built specifically for documenting Vue components. While documentation.js will do a great job of helping you document your methods, vuese takes it a step further by letting you add documentation to your props and components. It's incredibly easy to use.

I pretty much learned everything I needed to know from this blog post.