做文档真是个相当糟糕的体验……虽然我本来想用XML,但是那一大堆尖括弧实在是让人难受。于是megamijs的代码攒到2000行的时候我就考虑了文档语言的问题。
{dy}种设计出来的语言叫md,vim中的截图是这样:
(顺便在这里赞一下vim,自定语法的功能实在强大)
md是一种带结构的数据语言,md元素用< >包住。以冒号(:)开始的行会解释成元素,其他位置则用\开始一个元素。像:开始的那些元素,遇到换行,<或者;之前都认为是“命令区”。md{zh1}会转换成XML。
但是md设计的实在有点复杂(和有点TeX)。这个东西适合写书,不适合写API文档。
所以新设计的语言叫ygd,它取消了元素,一行若以:开始会解释成命令,此外还有些字符开始也会解释成特殊的指令(比如~会解释成desc命令。)ygd的这种(命令主导)设计让它可以支持多趟(multi-pass)处理。vim中ygd截图是这样:
在megamijs用的文档浏览器中,每个ygd文件都会经过两趟处理,一趟是处理整个文件并提取出所有的API项目(ns,类,类属等)。在确认要查看某个项目的细节时,ygd又会把ygd文档中“那个东西”代表的那段ygd取出并处理成HTML。ygd源文件在记事本等软件中打开后仍然可以阅读。
megamijs的github repo上已经有一个ygd了,是加载器的。各位可以去看看。