Wat*_*oto 9 c++ lua documentation-generation
我正在为Bitfighter游戏(http://bitfighter.org)记录一个新的和扩展的Lua API.我们的Lua对象模型是C++对象模型的一个子集,我需要记录的暴露给Lua的方法是C++中可用方法的一个子集.我想只记录与Lua相关的项目,而忽略其余的项目.
例如,对象BfObject是所有Lua对象的根,但它本身位于C++对象树的中间.BfObject有大约40种C++方法,其中大约10种与Lua脚本编写者相关.我希望我们的文档将BfObject显示为根对象,并仅显示那10个相关方法.我们还需要以一种使方法的继承清晰的方式显示其子对象.
目前我们可以假设所有代码都是用C++编写的.
一种想法是以某种方式标记我们想要记录的对象,使得诸如doxygen之类的系统知道要查看什么并忽略其余部分.另一种方法是以这样的方式预处理C++代码,即删除所有不相关的位,并记录像doxygen这样的东西.(我实际上使用luadoc这种方法已经相当远了,但找不到让luadoc显示对象层次结构的方法.)
可能有用的一件事是每个Lua对象类都以一致的方式与其父类一起注册.
有越来越多的游戏使用Lua编写脚本,其中许多都有不错的文档.有没有人对如何生产它有一个很好的建议？
PS为了澄清,我很高兴使用任何可以完成这项工作的工具 - doxygen和luadoc只是我熟悉的例子.
我找到了一个解决方案，虽然不理想，但效果很好。我拼凑了一个 Perl 脚本，它遍历所有 Bitfighter 源代码并生成第二组“假”源代码，其中仅包含我想要的元素。然后我可以通过 Doxygen 运行这个辅助源并获得 95% 的我正在寻找的结果。
我宣布胜利。
这种方法的一个优点是我可以以一种“自然”的方式记录代码，并且不需要担心标记什么是进出的。该脚本足够聪明，可以从代码结构中找出答案。
如果有人感兴趣，可以在 Bitfighter 源档案中找到 Perl 脚本，网址为https://code.google.com/p/bitfighter/source/browse/luadoc.pl。它只完成了大约 80%，并且缺少一些非常重要的项目（例如正确显示函数参数），但结构已经存在，并且我很满意该过程将起作用。该脚本将随着时间的推移而改进。
该过程的（非常初步的）结果可以在http://bitfighter.org/luadocs/index.html中查看。模板几乎没有经过修改，因此它具有非常“普通”的外观，但它表明事情或多或少是有效的。
由于一些评论者建议使用 Doxygen 不可能生成良好的文档，因此我应该指出，我们的内联文档几乎尚未添加。要了解它们的外观，请参阅 Teleporter 类。它不是很好，但我认为它确实驳斥了 Doxygen 总是生成无用文档的观点。
我目前最遗憾的是，我的解决方案实际上是一次性的，并没有解决我认为社区日益增长的需求。也许在某个时候，我们将标准化合并 C++ 和 Lua 的方法，并且创建通用文档工具的任务将更易于管理。
PS您可以看到原始源文件中的标记是什么样的...请参阅https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp，然后搜索 @luaclass