jsdoc使用手册

发表于 JS 分类,标签:

 

 

 

 

 

jsdoc使用手册

20190730-wuwg

 

 


 

目录

1. 概述 3

2. jsDoc 3

2.1 前置条件 3

2.2 安装淘宝镜像 3

2.3 全局安装jsdoc 3

2.4 使用jsdoc 5

2.5 jsdoc在线手册 7

2.6 jsdoc命令行参数 7

2.7 jsdoc配置文件解释 9

2.8 vscode 中自动生成jsdoc注释的两个插件 10

3. jsdocVue项目中的使用 11

3.1 安装依赖 jsdoc, jsdoc-vuejs 11

3.2 修改配置文件.jsdoc.conf.json 11

3.3 .jsdoc.conf.json完整配置 12

3.4 修改package.json中的命令行 13

3.5 jsdoc-vue使用范例 13

3.6 运行jsdoc命令 14


 

1. 概述

随着前端工程越来越重量级前端组件化,模块化已经成为前端开发的规范,当模块越来越多,组件越来越复杂,模块之间的依赖越来越强烈的时候,组件对外暴露的API显得尤为重要,因此,前端代码文档化势在必行。本文档主要给大家讲述前端文档化利【jsDoc

 

2. jsDoc

2.1 前置条件 

必须安装node 环境,node中默认自带npm

另外没安装淘宝镜像的用户,可以安装淘宝镜像cnpm代替npm, 以下实例中,命令行中使用的都是cnpm, 没安装cnpm的用户,请使用npm代替cnpm

2.2 安装淘宝镜像

npm install -g cnpm --registry=https://registry.npm.taobao.org

 

2.3 全局安装jsdoc 

 cnpm install  jsdoc  -g

 image.png


安装成功会出现以下界面

 image.png

jsdoc -v

输入上述命令,可查看版本号,显示出版本号,说明安装成功了!

 


2.4 使用jsdoc 

新建一个项目 jddoc 文件夹,里面新建一个index.js

 image.png

内容如下:

 

/**

* @name Person

* @description Person, 代表一个人实例.

* @constructor

* @param {string} name 人的姓名

* @param {number} age - 年龄

*/

function Person(name, age) {

this.name = name;

this.age = age;

}

Person.prototype={

/**

* @description 获取人的姓名

* @returns {string|*} 人的姓名

*/

getName:function(){

return this.name;

},

/**

* @description 设置人的年龄

* @param age {number} 年龄

* @returns {*} 无返回值

*/

setAge:function(age){

this.age = age;

}

};

 

 

 

 

运行命令

jsdoc index.js

image.png

会动态生成 out文件夹,里面为此次生成的API文档

 image.png

 image.png

用浏览器打开index.html 如下图

 

 image.png

 

 

2.5 jsdoc在线手册

http://www.dba.cn/book/jsdoc/JSDOCKuaiBiaoQianBLOCKTAGS/CONSTRUCTS.html

 

 

2.6 jsdoc命令行参数

jsdoc -h

可以查找出jsdoc中所有的命令行参数

 

 image.png

-c,  -r 是最常用的两个,其他配置可以查看2.5提到的手册。

-c <value>

--configure <value>

JSDoc配置文件的路径。默认为安装JSDoc目录下的conf.jsonconf.json.EXAMPLE

-r--recurse

扫描源文件和导览时递归到子目录。

 

 

2.7 jsdoc配置文件解释

 

配置文件,文件名通常定义为 .jsdoc-conf.json

 

 

image.png


jsdoc -c  .jsdoc-conf.json

生成文件Template 模板大概有以下种类

 

2.8 vscode 中自动生成jsdoc注释的两个插件

  add jsdoc comments 

安装成功后重启,选中方法(方法名+括号参数),然后按下F1,选中命令Add Doc Comments 即可。

Document This 

选中方法 按两次快捷键 ctrl+alt+D 就可以了。

 

3. jsdocVue项目中的使用

3.1 安装依赖 jsdoc, jsdoc-vuejs

cnpm install --save-dev jsdoc  jsdoc-vuejs

注意, vue的版本以及对应的编译程序vue-template-compiler

如: 用的是  vue@2.6  那么就需要 vue-template-compiler@2.6

 

选择性安装生成文件模板,下面两个任选一个就行

安装minami,  模板配置:"template": "./node_modules/minami"

cnpm install --save-dev minami

 

安装ink-docstrap,  模板配置:"template": "./node_modules/ink-docstrap/template"

cnpm install --save-dev ink-docstrap

3.2 修改配置文件.jsdoc.conf.json

找到配置项中plugins, source, opts”,(如果项目中没有的话,那么自己新建一个.jsdoc.conf.json文件 )

 

{

  "plugins": [

    "node_modules/jsdoc-vuejs"

  ],

  "source": {

    "includePattern": "\\.(vue|js)$"

  },

  "opts": {

    "template": "./node_modules/minami"

  }

}

3.3 .jsdoc.conf.json完整配置

{

// tags: 用来指定tag库,tags下面有2个属性,分别是

// allowUnknownTags : 用来告诉JSDoc如何处理标签库以外的tag,

// 设为false时,JSDoc不会处理标签库以外的tag,但会记录一个警告,默认为true

// dictionaries: 数组格式,指定标签库,标签库越靠前,优先度越高

"tags": {

// 允许使用自定义tag

"allowUnknownTags": true,

// 定义tag集

"dictionaries": [ "jsdoc" ]

},

// 递归的层级

"recurseDepth": 10,

// 顾名思义是用来指定源文件的,在其之下包含了4个属性

"source": {

// include: 源文件路径数组 【order-1】

"include": ["./src", "package.json"],

// exclude: 排除文件路径数组 【order-4】

"exclude": [],

// includePattern: 接受一个正则表达式,当文件名匹配这个正则时,执行JSDoc, 【order-2】

// "includePattern": "\\.(vue|js)$" 将以.js, .vue结尾的文件作为源文件

"includePattern": "\\.(vue|js)$",

// excludePattern: 接受一个正则表达式,当文件名匹配这个正则时,JSDoc忽略该文件

// 忽略以_开头的文件夹及文件 【order-3】

"excludePattern": "(^|\\/|\\\\)_"

},

// 配置额外的插件,如markdown插件,与此同时,JSDoc也可以编写自定义插件做额外的处理。

// jsdoc-vuejs 处理vue文件

// jsdoc-export-default-interop: 处理es6

// "./node_modules/jsdoc-export-default-interop/dist/index"

 

"plugins": ["./node_modules/jsdoc-vuejs"],

// 可以用来配置默认template的格式,或另外指定自定义的template

"templates": {

"cleverLinks": false,

"monospaceLinks": true,

"useLongnameInNav": false,

"showInheritedInNav": true

},

// opts: 命定行参数可以在此属性下配置,列如:

"opts": {

// 文档输出路径 -d

"destination": "./static/doc",

// 设置文件编码 -e

"encoding": "utf8",

// 将标记有[@private 标签][tags-private.md]的标识符也生成到文档中。默认情况下,不包括私有标识符。 -p

"private": true,

// 扫描源文件和导览时递归到子目录。 -r

"recurse": true,

// 设置【生成文件模板】 ink-docstrap 和 minami 模板

// "template": "./node_modules/ink-docstrap/template"

"template": "./node_modules/minami"

}

}

 


 

3.4 修改package.json中的命令行

 

找到配置项中的scripts”添加以下命令

 

 

"doc": "jsdoc -r -c .jsdoc.conf.json",

 

3.5 jsdoc-vue使用范例 

jsdoc-vue就以下四个块标签

  • @vue-prop

  • @vue-data

  • @vue-computed

  • @vue-event

    使用示例如下:

    <template>

    <div>Hello world!</div>

    </template>

     

    <script>

    /**

    * @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: false,

    },

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

    }

    }

    }

    </script>

     

3.6 运行jsdoc命令 

运行命令

npm run  doc

文档输出,会保存在static 文件夹下的doc文件夹中。

 

 image.png


0 篇评论

发表我的评论