https://github.com/Kocal/jsdoc-vuejs
📖 A JSDoc plugin for documenting .vue files.
https://github.com/Kocal/jsdoc-vuejs
jsdoc jsdoc-plugin vue-files vuejs
Last synced: 10 months ago
JSON representation
📖 A JSDoc plugin for documenting .vue files.
- Host: GitHub
- URL: https://github.com/Kocal/jsdoc-vuejs
- Owner: Kocal
- License: mit
- Created: 2017-08-10T19:47:21.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T16:47:40.000Z (over 3 years ago)
- Last Synced: 2024-10-12T23:12:56.376Z (over 1 year ago)
- Topics: jsdoc, jsdoc-plugin, vue-files, vuejs
- Language: JavaScript
- Homepage:
- Size: 4.56 MB
- Stars: 235
- Watchers: 4
- Forks: 40
- Open Issues: 57
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
JSDoc for VueJS
===============
[](https://badge.fury.io/js/jsdoc-vuejs)
[](https://travis-ci.org/Kocal/jsdoc-vuejs)
[](https://ci.appveyor.com/project/Kocal/jsdoc-vuejs)
[](https://codecov.io/gh/Kocal/jsdoc-vuejs)
[](https://www.codacy.com/app/kocal/jsdoc-vuejs?utm_source=github.com&utm_medium=referral&utm_content=Kocal/jsdoc-vuejs&utm_campaign=Badge_Grade)
A JSDoc plugin for listing props, data, computed data, and methods from `.vue` files.
:warning: This branch is for Vue 3. If you still use Vue 2, please see [`3.x` branch](https://github.com/Kocal/jsdoc-vuejs/tree/3.x).
---
## Requirements
- Node 10+
- Vue 3
## Installation
```bash
$ npm install --save-dev jsdoc jsdoc-vuejs
```
You also need to install `@vue/compiler-sfc` that match your Vue version:
```bash
$ npm install --save-dev @vue/compiler-sfc
```
## Usage
Your should update your JSDoc configuration to enable JSDoc-VueJS:
```json
{
"plugins": [
"node_modules/jsdoc-vuejs"
],
"source": {
"includePattern": "\\.(vue|js)$"
}
}
```
Update your .vue files with one of the following tags:
- `@vue-prop`
- `@vue-data`
- `@vue-computed`
- `@vue-event`
All of those tags work the same way than [`@param` tag](http://usejsdoc.org/tags-param.html).
```vue
Hello world!
/**
* @vue-prop {Number} initialCounter - Initial counter's value
* @vue-prop {Number} [step=1] - Step
* @vue-data {Number} counter - Current counter's value
* @vue-computed {String} message
* @vue-event {Number} increment - Emit counter's value after increment
* @vue-event {Number} decrement - Emit counter's value after decrement
*/
export default {
props: {
initialCounter: {
type: Number,
required: true,
},
step: {
type: Number,
default: 1,
},
},
data () {
return {
counter: 0,
}
},
computed: {
message() {
return `Current value is ${this.counter}`;
}
},
methods: {
increment() {
this.counter += 1;
this.$emit('increment', this.counter);
},
decrement() {
this.counter -= 1;
this.$emit('decrement', this.counter);
}
}
}
```
## Supported templates
The rendering engine has been rewritten in v2, it can supports every JSDoc templates that exists.
Actually, it supports 4 templates:
- Default
- [Docstrap](https://github.com/docstrap/docstrap)
- [Minami](https://github.com/nijikokun/minami)
- [Tui](https://github.com/nhnent/tui.jsdoc-template)
If you use a template that is not supported, it will use the default one as a fallback.
Feel free to open an issue/pull request if your template is not supported!
Default
Docstrap
Minami
Tui
## Testing
### Install Dependencies
```bash
$ git clone https://github.com/Kocal/jsdoc-vuejs
$ cd jsdoc-vuejs
$ yarn install
# For testing the example docs
$ cd example
$ yarn install
```
#### Generate documentations
```bash
$ cd example
# Generate docs for every renderer
$ yarn docs:all
# or one by one
$ yarn docs # default jsdoc template
$ yarn docs:docstrap
$ yarn docs:minami
$ yarn docs:tui
```
### Unit
```bash
$ yarn test
```
### E2E
Before running integration tests with [Cypress](https://cypress.io),
you should generate documentation with all renderers:
```bash
$ cd example
$ yarn docs:all
```
And then run Cypress:
```bash
$ cd ..
$ yarn cypress run
```
## License
MIT.