11

我正在为游戏 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 只是我比较熟悉的示例。

4

3 回答 3

2

我找到了一个解决方案，虽然不理想，但效果很好。我拼凑了一个 Perl 脚本，该脚本遍历所有 Bitfighter 源代码并生成第二组“假”源，其中仅包含我想要的元素。然后我可以通过 Doxygen 运行这个辅助源，并得到我正在寻找的 95% 的结果。

我宣布胜利。

这种方法的一个优点是我可以以一种“自然”的方式记录代码，而不必担心标记什么进什么出。该脚本足够聪明，可以从代码结构中弄清楚。

如果有人感兴趣，可以在https://code.google.com/p/bitfighter/source/browse/luadoc.pl的 Bitfighter 源档案中找到 Perl 脚本。它只完成了大约 80%，并且缺少一些非常重要的项目（例如正确显示函数 args），但结构就在那里，我很满意这个过程可以正常工作。脚本会随着时间的推移而改进。

该过程的（非常初步的）结果可以在http://bitfighter.org/luadocs/index.html中看到。模板几乎没有被修改过，所以它看起来很“普通”，但它表明事情或多或少是有效的。

由于一些评论者建议使用 Doxygen 生成好的文档是不可能的，我应该注意到我们几乎没有添加任何内联文档。要了解它们的外观，请参阅 Teleporter 类。这不是超级好，但我认为它确实驳斥了 Doxygen 总是产生无用文档的观点。

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

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

于 2012-09-13T13:41:00.937 回答
1

通过 C++ 代码的命名空间（也可以是类）排除，但不排除 lua 代码

EXCLUDE_SYMBOLS = myhier_cpp::*

在 doxygen 配置文件或樱桃中选择要排除的内容

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

/// @endcond

在你的 C++ 代码中。

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

通过排除进行分离可能是最具针对性的方法，但这将涉及一个额外的工具来解析代码、标记相关的 lua 部分并将排除添加到代码中。（此外，您还可以使用此标记单独呈现特殊信息，例如图形，并通过图像将它们添加到您的文档中，至少使用 Doxygen 很容易做到这一点。）。由于必须有某种 lua 代码的指示，因此该标记可能不太难推导。

于 2012-09-12T12:53:41.020 回答
0

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

一个优点是您也可以使用相同的工具来记录您的 lua 代码。一个缺点是该项目似乎没有维护。也可能无法记录复杂的对象层次结构，就像提问者提到的那样。

我自己对它进行了一些关于 c++ 的小调整。看看这里。

于 2018-03-28T08:04:48.033 回答