JS 工具库文档化 - JSDoc

JSDoc 是一个自动化生成 JavaScript 文档工具,它是利用对 JavaScript 函数的特定注释来编译成 HTML 文件的一个文档工具。

安装


全局安装或者局部安装:

npm install jsdoc -g

npm install jsdoc -save-dev

基本使用

只要在 JavaScript  中写好注释,利用命令即可:

jsdoc a.js b.js ...

当然我们也可以在项目下定义 jsdoc.json 配置文件,通过 -c 参数来指定:

jsdoc -c jsdoc.json

可以在 package.json 中的 scripts 添加命令:

{
    "scripts": {
      "docs": "jsdoc -c jsdoc.json"
  }
}

这样我们就可以通过在项目下执行 npm run docs 命令来生成文档了。

配置文件

常用的配置文件

{
  "source": {
    "include": [ "src/" ],
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "templates/default",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": false
  }
}
  • source 表示传递给 JSDOC 的文件
  • source.include 表示 JSDOC 需要扫描哪些文件
  • source.exclude 表示 JSDOC 需要排除哪些文件
  • opts 表示传递给 JSDOC 的选项
  • opts.template 生成文档的模板,默认是 templates/default
  • opts.encoding 读取文件的编码,默认是 utf8
  • opts.destination 生成文档的路径,默认是 ./out/
  • opts.recurse 运行时是否递归子目录
  • opts.verbose 运行时是否输出详细信息,默认是 false

注释

/**
* @author Mondo
* @description list 数据结构 转换成 树结构
* @param {Array} data 需要转换的数据
* @param {String} id 节点 id
* @param {String} pid 父级节点 id
* @param {String} child 子树为节点对象的某个属性值
* @param {Object} labels 需要新增的字段名集合 { label: 'category_name' }
* @return {Array}
*
* @example
* formatListToTree({data: [{id:1}, {id: 2}, {id: 3, pid: 1}]})
* =>
* [ { id: 1, children: [ {id: 3, pid: 1} ] }, { id: 2 } ]
*/

function formatListToTree({
  data = [],
  id = "id",
  pid = "pid",
  child = "children",
  labels = null
}) {
...
}

常见的 JavaScript 块级注释,必须以 /** 开头,不然会被忽略掉。


下面介绍一些常见的级块标签:

  • @author 该类/方法的作者。
  • @class 表示这是一个类。
  • @function/@method 表示这是一个函数/方法(这是同义词)。
  • @private 表示该类/方法是私有的,JSDOC 不会为其生成文档。
  • @name 该类/方法的名字。
  • @description 该类/方法的描述。
  • @param 该类/方法的参数,可重复定义。
  • @return 该类/方法的返回类型。
  • @link 创建超链接,生成文档时可以为其链接到其他部分。
  • @example 创建例子。

主题


JSDoc 默认的主题可能不近如人意,不过大型交友网站上给我们提供了还不错的主题,只要我们对应 install 下来配置就行。推荐两款还不错的主题:


配置主题:

  • 下载
npm install docdash --save-dev
  • jsdoc.json 文件中配置
{
  "opts": {
    "template": "node_modules/docdash"
  }
}

模版

对主题还是不满意,我们也可以在 jsdoc.json  中指定自己的模版

{
  "templates": {
    "cleverLinks": true,
    "default": {
      "layoutFile": "plugins/layout.tmpl"
    }
  }
}

模版文件其实就是主题中自定义模版

部署

这一部分可参考 travis-cli 持续集成。


js-utils 是作者君利用 JSDoc  搭建的一个日常函数工具库,可以参考里面的配置。


参考:
jsdoc


欢迎关注公众号,大家一起共同交流和进步。

现在开始,从心出发

962 声望
20 粉丝
0 条评论
推荐阅读
摸着文档过河的 Canvas 绘制
这几天接了个活,需要做一个停车场示意图,首先想到的是使用 Canvas 来绘制。由于前期只是粗浅的使用过 Canvas,而没有正式的在项目中使用过,这次也是摸着文档过河😂。

Mondo阅读 2.2k

从零搭建 Node.js 企业级 Web 服务器(零):静态服务
过去 5 年,我前后在菜鸟网络和蚂蚁金服做开发工作,一方面支撑业务团队开发各类业务系统,另一方面在自己的技术团队做基础技术建设。期间借着 Node.js 的锋芒做了不少 Web 系统,有的至今生气蓬勃、有的早已夭折...

乌柏木142阅读 11.9k评论 10

从零搭建 Node.js 企业级 Web 服务器(十五):总结与展望
总结截止到本章 “从零搭建 Node.js 企业级 Web 服务器” 主题共计 16 章内容就更新完毕了,回顾第零章曾写道:搭建一个 Node.js 企业级 Web 服务器并非难事,只是必须做好几个关键事项这几件必须做好的关键事项就...

乌柏木60阅读 6k评论 16

再也不学AJAX了!(二)使用AJAX ① XMLHttpRequest
「再也不学 AJAX 了」是一个以 AJAX 为主题的系列文章,希望读者通过阅读本系列文章,能够对 AJAX 技术有更加深入的认识和理解,从此能够再也不用专门学习 AJAX。本篇文章为该系列的第二篇,最近更新于 2023 年 1...

libinfs39阅读 6.2k评论 12

封面图
从零搭建 Node.js 企业级 Web 服务器(一):接口与分层
分层规范从本章起,正式进入企业级 Web 服务器核心内容。通常,一块完整的业务逻辑是由视图层、控制层、服务层、模型层共同定义与实现的,如下图:从上至下,抽象层次逐渐加深。从下至上,业务细节逐渐清晰。视图...

乌柏木39阅读 7.1k评论 6

CSS 绘制一只思否猫
欢迎关注我的公众号:前端侦探练习 CSS 有一个比较有趣的方式,就是发挥想象,绘制各式各样的图案,比如来绘制一只思否猫?思否猫,SegmentFault 思否的吉祥物,是一只独一无二、特立独行、热爱自由的(>^ω^&lt...

XboxYan42阅读 2.8k评论 14

封面图
还在用 JS 做节流吗?CSS 也可以防止按钮重复点击
举个例子:一个保存按钮,为了避免重复提交或者服务器考虑,往往需要对点击行为做一定的限制,比如只允许每300ms提交一次,这时候我想大部分同学都会到网上直接拷贝一段throttle函数,或者直接引用lodash工具库

XboxYan34阅读 2.2k评论 2

封面图

现在开始,从心出发

962 声望
20 粉丝
宣传栏