用ldoc给cocos2dx-lua项目生成API文档

最近要对cocos2dx-lua的项目编写API文档， 我的想法是类似与java doc的做法，在程序中写注释，通过脚本将注释提取生成， 这样只需要维护代码中的注释就可以了

调查了一下，目前支持这种方式的有Doxygen luadoc ldoc， 进一步比较网上资料决定采用ldoc方式

以下是mac系统的集成方法

1.  ldoc github地址 https://github.com/stevedonovan/ldoc 下载代码

2.  penlight库 github地址 https://github.com/stevedonovan/Penlight 下载代码

3.  lfs github地址 https://github.com/keplerproject/luafilesystem 下载代码

4.  通过make命令将lfs编译成lfs.so

5.  新建文件夹（这里命名为luadoc） 将ldoc库中的ldoc文件夹和ldoc.lua拷贝到其中

6.  将lfs.so拷贝到luadoc中

7.  将penlight库中的pl文件夹拷贝到luadoc中

8.  在luadoc文件夹中新建config.ld 内容如下(将xxx替换为实际内容 file为要生成注释的lua文件夹或者文件的路径)

project='XXX'
title='XXXXX'
description='XXXXX'
file='XXXXX'

9. cd到luadoc文件夹 执行命令lua ldoc.lua .

10. luadoc中会生成doc文件夹 打开index.html就可以看到注释了

更多的命令及用法可以参见以下文章

http://www.cnblogs.com/jncpp/p/4230315.html

http://m.oschina.net/blog/188909

http://stevedonovan.github.io/ldoc/

另外由于ldoc是用lua编写的，因此我结合实际情况对部分代码进行了修改

1.  ldoc_css.lua第126行将margin-left改完18em(原来的左侧宽度太小显示不下)

2.  注释掉128行， 这样网页的总宽度就和实际屏幕宽度保持一致

 

转载于:https://www.cnblogs.com/ColaZhang/p/4987173.html