jsDoc的使用文档

个人的总结，有不准确的地方欢迎大家留言指出

• 安装
  • npm init -y
  • npm i -D jsdoc
    • package.json中可以看到jsdoc的版本信息
  • 新建一个jsdoc.json文件
    • {
      “source”:{
      “include”:[“src”],
      “includePattern”:".js$",
      “excludePattern”:"(node_modules/docs)"
      },
      “plugins”:[“plugins/markdown”],
      “templates”:{
      “cleverLinks”:true,
      “monospaceLinks”:true
      },
      “opts”:{
      “recurse”:true,
      “destination”:"./docs/",
      “template”:“custom-template”
      }
      }
  • 修改package.json文件
    • “scripts”: {
      “doc”: “jsdoc -c jsdoc.json”
      },
  • 新建src文件夹，输入skmap.js文件(输入文档必须是js类型不能是html类型)，执行npm run doc
  • 回车后，在当前项目文件根目录下会生成一个docs文件夹，里面有3个文件夹fonts、scripts、styles分别是生成文档的字体、脚本和css样式,根目录下的html文档文件就是JSDoc文档，在浏览器中打开该文件
• 格式
  /**
  • @标签 文档内容
    */
• 常用功能标签：
  desc/description 描述方法、变量，放在第一排可省略
  method/function 方法名
  param 参数，可定义类型
  property 属性，可定义类型
  return 方法返回值，可定义类型
  todo 描述函数的功能
  global 表示变量是否是全局
  constructs 表明是构造函数
  default 默认值
  alias 别名
  event 事件
  example 示例
  type 变量类型
  module 标明当前文档模块文档信息标签
  version 版本信息
  author 作者
  license 开源协议
  link 链接
• 使用
  • 变量声明
    //@ts-check
    • /**
      *Name
      *@type {string}------------表示name这个变量的类型只能是字符串类型
      */
      const name=‘Joe’
    • /**
      *Array of grades
      *@type {Array}------------表示grades这个变量的类型只能是数组类型,且数组中只能是数字类型的值，可以不加限定条件
      */
      const grades=[98,85,73,99]
    • /**
      *todo object描述
      *@type {{id:number,text:string}}------------表示todo这个变量的类型只能是object,而且限定了键值对的类型
      */
      const todo={
      id:1,
      text:“Hello”
      }
  • 函数声明
    • /**
      *total带参函数的描述
      *@param {number} amount --amount参数的类型
      *@param {number} item --item参数的类型
      *@returns {string} --函数返回值类型
      *@example 举例子
      */
      const total = (amount,item)=>{
      return ${amount+item*amount};
      }
      console.log(total(20,0.5));
  • 构造函数声明
    • /**
      *@class
      */
      function thrdLayerHelper(sgs) {
      this.sgs = sgs;
      this.shape= null;
      }
      thrdLayerHelper.prototype.createCircle，如在构造函数原型上加的方法以函数声明中编写的规范进行注解
  • 模块(js文件)引入
    • 导出模块 @module mokuai(文件名称)
      /**
      *@param {number} n1 --n1参数的类型
      *@param {number} n2 --n2参数的类型
      *@returns {number}
      */
      exports.add = (n1,n2)=>n1+n2
    • 在需要引入的地方按需引入
      const {add}=require (‘mokuai’);