简单的文档生成工具
- 根据代码注释生成文档
- 根据markdown中注释替换文件
lazy-doc 懒人文档生成工具
install
npm install lazy-doc
usage
var doc = require('lazy-doc');
doc(folder, output, config);
示例
var doc = require('lazy-doc');
doc(__dirname + '/src', __dirname + '/readme.md',{
default: '### {key}\n{value}', // 修改默认规则
source: '### 源代码地址: {value}' // 自己制定规则
});
命令行工具使用
# 需要先全局安装lazy-doc，`npm install -g lazy-doc`
lazydoc <path|folder> -o dest_file --config config_path
lazydoc readme.md
lazydoc filename -o dest_filename
# 使用文件夹和配置项
lazydoc folder --config doc.config.js
# 使用glob规则匹配文件
lazydoc "src/*.{ts|js}" -o test.md配置项说明
ignoreExt 忽略的文件扩展名,数组格式
默认为['.bmp', '.jpg', '.gif', '.png']
templates 模板配置
例如
{
'class': '\n# 类 {value.trim()}',
}
beforeParse 转换文件前触发
| 参数 |
说明 |
类型 |
| ctx |
写入文件信息 |
Object |
| ctx |
.filepath 要转换的文件的路径 |
string |
| ctx |
.origin 文件内容 |
string |
beforeWrite 写入文件前调用
| 参数 |
说明 |
类型 |
| ctx |
写入文件信息 |
Object |
| ctx |
.filepath 要写入的路径 |
string |
| ctx |
.content 文件内容 |
string |
lib/utils 函数
getMarks 从代码中查找注释模块并取得@标记
返回值 {[Mark]} 标记列表
getNotes 取得代码中的块注释内容并清理掉前面的*
| 参数 |
说明 |
类型 |
| source |
代码内容 |
string |
返回值 {[Note]} 注释内容
{Object} Note 解析后注释内容结构
| 属性 |
说明 |
类型 |
| block |
注释原文 |
string |
| content |
注释内容(清理掉前面的*后剩余部分) |
string |
| position |
注释开始位置 |
number |
| nextLine |
注释结束后后面一行内容（注释结束后不是换行符，则直接取注释后内容） |
string |
getNoteMark 取得注释中用mark标记的代码
| 参数 |
说明 |
类型 |
| note |
|
Object |
| source |
|
string |
返回值 {Object} 注释解析后的标记内容
parseNoteMark 将mark转换为markdown文件
| 参数 |
说明 |
类型 |
| marks |
Mark标记列表 |
|
| config |
配置项 |
|
parseParam 解析参数含义
| 参数 |
说明 |
类型 |
| value |
要转换的参数解释内容 |
string |
返回值 {Parsed} 解析后的参数
{Object} Parsed 参数解析后数据对象
| 属性 |
说明 |
类型 |
| type |
参数数据类型 |
string |
| name |
参数名称 |
string |
| desc |
参数说明 |
string |
| optional |
是否必填 |
boolean |
书写规范
- 注释以
/**开头,并以*/结尾.并且其中包含以@开头的说明
- @标记只能出现在行的开头(之前可以加一个*),行中间的@标记将不被作为格式标记处理
- 一个注释内的第一个@标记后面将表示该注释模块的类型,例如 函数,模块,变量等
Todo
- [ ] 重新梳理数据和阶段
- 阶段及事件
- 读取
- 转换mark(mark, {markIndex, prevMark, nextMark, fileInfo})
- 排序并写入文件
- 数据结构 []
- file: '' 文件路径
- content: '' 文件内容
- dest: '', 写入文件路径
- blocks
- type: 类型 code代码,note注释
- content: 内容
- position: 开始位置
- marks: [] 内部注释列表
- origin: ''
- name: ''
- position 注释在content中的位置
- translate: {}
- result
- [ ] 使用ast转换??