JSDoc javascript 注释

发表于   |   分类于

JSDoc 是根据 JavaScript 文件中的注释信息，生成静态文件的工具，使用简单方便。

JSDoc 官方文档
JSDoc 中文文档

在使用 JSDoc 时，发现无法定义指向项目内的链接。@link 和 @see 语法创建内联标签连接到文档中的其它项 或 外部URL，无法使用相对路径连接到项目内的地址，但可以通过自定义插件实现该功能。

plugins/demo.js 文件中内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
// demo{/#/cesium|参考样例}
exports.handlers = {
  beforeParse: (e) => {
    const result = e.source.match(/demo\{[^\}]+\}/);
    if (result && result[0]) {
      const value = result[0].replace('demo{', '').replace('}', '').split('|');
      if (value && value.length > 1) {
        e.source = e.source.replace(result[0], `<a href="${value[0]}">${value[1]}</a>`);
      }
    }
  },
};

conf.json 文件中内容如下：

1
2
3
{
  "plugins": ["plugins/demo"]
}

命令

1
jsdoc -c conf.json source/**/* -d static/doc