Lazy-doc NPM | npm.io

简单的文档生成工具

根据代码注释生成文档
根据markdown中注释替换文件

lazy-doc 懒人文档生成工具

参数	说明	类型
folder	要生成文档的代码所在文件夹例如: __dirname + '/src'	string
output	输出位置。当为string时，表示要写入的文件路径当为Function时，文档计算完毕后的回调,有两个参数,所有文档合并后的string和分析后的文档列表	string	Function
options	配置项。配置@标记后的输出规则,包含两个参数key和val,当时字符串时自动替换{key}和{value}为文档值,是函数时将被替换为返回内容. 可参考https://github.com/laomu1988/lazy-doc/blob/master/src/template.ts	object

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

更新记录 (https://github.com/laomu1988/lazy-doc/blob/master/package.json)

lib/utils 函数

getMarks 从代码中查找注释模块并取得`@`标记

参数	说明	类型
source	源文件

返回值 {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转换??