注释规范(注释标签)
-
mokdoc的块注释以
/*-- 开头,以*/ 结尾,mokdoc目前只会提取这样的块注释生成文档。后续会兼容传统的块注释风格。默认支持的标签列表:
名称 允许多个 描述 第一行 第一行,无标签。描述文件、函数、对象等的功能作用 -p 是 参数描述。参数类型,注释的时候可直接用简写: string: 字符串,简写 str
function: 函数,简写 fn
number: 数字,简写 num
object: 对象(纯对象),简写 obj
regexp: 正则表达式,简写 reg
date: 日期
如果参数是可选参数,要将参数名用中括号括起来,例如:-p num [sliderCount] 滑动个数
如果可选参数有默认值,将默认值写在参数名后面,例如:-p num [sliderCount = 1] 滑动个数
-r 返回值描述 -as 作为什么名称,忽视此注释下边代码里的名称 -ns 使用什么命名空间 -addto 将当前文件里接下来的方法注释添加到某个对象、类或命名空间下面 -note 是 使用提示、注意事项 -file 标识这是文件描述 -fn 标识这是一个函数(方法) -class 标识这是一个类 -static 标识这是静态属性、方法 -private 标识这是私有属性、方法 -know 标识这是知识库,同时指定知识名称 -dict 是 数据字典 -rel 是 链接到相关类、函数等。链接到相应的文档涉及到注释类型: 0: 普通注释
1: 数据字典
2: 知识库
简单示例:链接到普通注释Tab:-rel [0,Tab] 选项卡类
0为注释类型,Tab为工具提取的注释id,就是类名或带命名空间的函数名等。后面为简单描述,可无。链接到数据字典clickAction:[1,clickAction] 点击上报的动作属性值字典
链接到知识库里的点击统计:[2,点击统计]
-eg 示例代码 -author 作者 -ver 版本号或修改日期 注:“允许多个”表示同一注释块里是否允许多次使用该标签。上表里为空的表示不允许多次使用,多次使用时最后一个有效。
可能你不喜欢上述标签名,那么可以给标签设置别名,设置方法:
注释示例
-
方法注释:
类注释:
生成的文档如下:
构建知识库:
生成的文档如下:
创建数据字典:
说明:“-create”表示要创建数据字典;“clickAction”是数据字典名字;后面是字典描述。
向数据字典添加值:
说明:“clickAction”是前面创建的数据字典;“sso_login_third_qq”和“sso_login_topbar”是添加到字典里的值;后面是值描述。
生成的文档如下:
更多示例请看:mokdoc-demo.js
配置与运行
-
请看mokdoc的GitHub:https://github.com/1144/mokdoc