前端开发服务框架

注释规范(注释标签)

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