前端和后端注释文档生成

前端和后端的 函数及api 说明文档生成总结，持续更新中 by Qzx

apiDoc的使用教程

# 全局安装
npm install apidoc -g   
# 查看是否安装成功,显示命令行参数
apidoc -h 
二、apidoc 常用命令说明
--file-filters
过滤器，指定应该解析的文件类型，后缀 （可以使用多个-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts"
--exclude-filters
过滤器用于选择不应该解析的文件
--input
指定输入的源目录名，项目文件的位置，默认为 ./ 例：apidoc -i myapp/
--output
指定输出的目录文件名，放置生成文档的位置，默认为 ./doc/，例：apidoc -o apidoc/
--template
指定要用的外部模板的路径，可以创建和使用自己的模板，默认使用全局的 node_modules/apidoc/template/ ，例：apidoc -t mytemplate/
--config
指定配置文件的路径 apidoc.json ./
--help
显示详细的帮助说明
--debug
--debug
显示调试的信息，默认为 false
三、具体使用
在项目文件夹新建apidoc.json;
在项目目录运行：
apidoc -i myapp/ -o apidoc/ -t mytemplate/
# 简写指令
apidoc
说明：上面的指令可以直接简写为 apidoc，没有任何参数时，默认从当前目录(包括子目录)下格式为(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文档并将输出写入 ./doc/。
四、基本配置（apidoc.json）
项目根目录下的 apidoc.json 可配置项包含有关项目的常用信息，如 标题，简短描述、版本和配置选项，如页眉/页脚设置或模板特定选项。
基本配置方式（apidoc.json）
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
在含有package.json文件的项目中配置(添加"apidoc":{}参数)
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
添加额外的 Header 和 Footer (不常用，在apidoc.json添加header和footer参数)
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
配置参数的详细说明(apidoc.json)
五、apiDoc 常用api说明
常用api：@api,@apiName,@apiGroup,@apiVersion,@apiDescription,@apiParam,@apiSuccess,@apiSuccessExample,@apiDefine,@apiError,@apiIgnore
基本例子(demo.js)
 * @api {get} /user/:id Request User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 * @apiParam {Number} id Users unique ID.
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 * @apiError UserNotFound The id of the User was not found.
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
说明：文档块以 /** 和 */ 结尾，其中@api为必须字段，格式同例子：@api + {请求类型} + 接口路径 + 接口描述，在生成的时候没有@api 的文档块会被忽略。@apiName 和 @apiGroup,在版本迭代时应保持一致，其他字段为可选。
@api (必须字段，没有会被忽略)
@api {method} path [title]
例：@api {get} /user/:id Users unique ID.
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
说明：1. 带括号的Fieldname将Variable定义为可选。2. =defaultValue 参数默认值。
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
  * @api {get} /user/:id
  * @apiSuccess (200) {String} firstname Firstname of the User.
  * @apiSuccess (200) {String} lastname  Lastname of the User.
    * @api {get} /user/:id
    * @apiSuccess {Boolean} active        Specify if the account is active.
    * @apiSuccess {Object}  profile       User profile information.
    * @apiSuccess {Number}  profile.age   Users age.
    * @apiSuccess {String}  profile.image Avatar-Image.
--file-filters
过滤器，指定应该解析的文件类型，后缀 （可以使用多个-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts"
--exclude-filters
过滤器用于选择不应该解析的文件
三、具体使用
命令行新建一个项目
mkdir jsDocDemo
cd jsDocDemo
npm init -y
新建一个demo.js,代码示例如下:
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
function Book(title, author) {
    this.title=title;
    this.author=author;
Book.prototype={
     * 获取书本的标题
     * @returns {string|*}
    getTitle:function(){
        return this.title;
     * 设置书本的页数
     * @param pageNum {number} 页数
    setPageNum:function(pageNum){
        this.pageNum=pageNum;