我应该如何记录用C++代码编写的Lua /对象模型？

Question

我的工作是记录一个新的和扩展的Lua的游戏比特战斗机(http://bitfighter.org)。我们的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只是我有点熟悉的例子。

Answer 1

我找到了一个解决办法，虽然不太理想，但效果很好。我拼凑了一个Perl脚本，它翻阅了所有的Bitfighter源代码，并产生了第二组“假”源代码，其中只包含了我想要的元素。然后，我可以运行这个第二来源通过氧气，并得到一个结果，是95%，我正在寻找的。

我要宣布胜利。

这种方法的一个优点是，我可以以“自然”的方式记录代码，而不需要担心标记什么内容和什么内容。这个脚本足够聪明，可以从代码结构中找到它。

如果有人感兴趣，Perl脚本可以在https://code.google.com/p/bitfighter/source/browse/luadoc.pl的Bitfighter源代码存档中获得。它只完成了80%左右，并且缺少了一些非常重要的项目(比如正确地显示功能args)，但是结构在那里，我很满意这个过程会工作。剧本会随着时间的推移而改进。

这个过程的(非常初步的)结果可以在http://bitfighter.org/luadocs/index.html上看到。模板几乎没有被修改，所以它有一个非常“股票”的外观，但它表明，事情或多或少的工作。

由于一些评论者认为不可能用DO2生成良好的文档，我应该指出，我们的内联文档几乎没有一个被添加。要了解他们的样子，请看电视班。这不是超级好，但我认为它确实驳斥了这样的观点，即氧气总是产生无用的文档。

在这一点上，我最大的遗憾是，我的解决方案实际上是一次性的，没有解决我认为社会上日益增长的需求。也许在某个时候，我们将对合并C++和Lua的方法进行标准化，创建一个通用文档工具的任务将更加易于管理。

你可以看到原始源文件中的标记是什么样子的.参见https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp，并搜索@luaclass

Answer 2

排除C++代码的命名空间(也可以是类)，但不排除lua代码

EXCLUDE_SYMBOLS = myhier_cpp::*

在doxygen配置文件或樱桃中，通过使用

/// @cond
class aaa {
  ...
  ...
}

/// @endcond

在c++代码中。

我个人认为，按名称空间分离更好，因为它反映了代码+文档中的分离，这导致了一个基于名称空间的方案，用于将纯c++与lua绑定分离。

通过排除分离可能是最有针对性的方法，但这将涉及一个额外的工具来解析代码，标记相关的lua部件并将排除添加到代码中。(此外，您还可以使用此标记分别呈现特殊的信息，如图形，并通过图像将它们添加到文档中，至少使用DO2很容易实现。)由于必须有某种lua代码的指示，所以标记可能不会太难派生。

Answer 3

另一个解决方案是使用LDoc。它还允许您编写C++注释，这些注释将由LDoc解析并包含在文档中。

优点是您也可以使用相同的工具来记录您的lua代码。一个缺点是这个项目似乎没有得到维护。也可能不可能记录复杂的对象层次结构，比如前面提到的发问者。

我自己用叉子对c++做了一些小的调整。看看这里。