14

我正在开发一个相当大的开源 RTS 游戏引擎（Spring）。我最近添加了一堆可由 Lua 调用的新 C++ 函数，我想知道如何最好地记录它们，同时也鼓励人们为许多现有的 Lua 调用编写/更新文档。

因此，我认为如果我最初可以将文档编写为 C++ 函数附近的 doxygen 注释，这可能会很好——这很容易，因为函数体显然准确地定义了函数的作用。但是，我希望使用引擎的游戏开发人员能够改进文档，他们通常对 git（我们使用的 VCS）或 C++ 了解甚少。

因此，如果有一种方法可以从 C++ 文件中自动生成 apidocs，而且还有一个类似于 wiki 的 Web 界面，以允许更广泛的受众更新评论、添加示例等，那将是理想的。

所以我想知道，是否存在一个集成了 doxygen 样式格式、对这些评论进行类似 wiki 的编辑（最好不允许编辑源文件的任何其他部分）和 git 的网络工具？（将通过 Web 界面更改的评论提交到特殊分支）

然后，我们开发人员可以不时合并此分支以将改进添加到主分支，同时开发人员对文档的任何改进都将最终在此 Web 工具上，只需将主分支合并到此特殊分支分支。

我还没有找到任何东西，怀疑这个特定的东西是否存在，所以欢迎任何建议！

4

1 回答 1

6

这确实是一个非常酷的想法，几年前我也非常需要类似的东西。不幸的是，至少在那时，我无法找到类似的东西。在 sourceforge 和freshmeat 上进行快速搜索今天也没有找到任何相关内容。

但我同意这样一个用户贡献文档的 wiki 前端会非常有用，我知道最近 Lua 社区也讨论了类似的事情（参见this）。

那么，也许我们可以确定要求以提出基本的工作草案/原型？

希望这能让我们以最少的功能启动这样一个项目，然后简单地将它作为一个开源项目（例如在 sourceforge 上）发布到野外，以便其他用户可以为它做出贡献。

理想情况下，可以使用统一补丁来应用以这种方式贡献的更改。此外，将修改限制为仅添加/编辑注释可能是有意义的，而不是允许任意修改文本，这可能通过使用简单的正则表达式来实现。

也许，人们可以通过修改现有的（已建立的）wiki 软件（如 mediawiki）来实现类似的功能。或者最好是已经使用 git 作为后端进行存储的东西。然后，主要需要迎合那些 Doxygen 风格的评论，并在其之上提供一个简单的界面。

再想一想，DoxyGen 本身已经提供了对生成 HTML 文档的支持，所以从这个角度来看，DoxyGen 可以如何扩展可能会很有趣，因此它可以很好地与这样的脚本后端集成，从而可以轻松嵌入式源代码文档的定制。

这可能主要归结为提供一个带有 doxygen 的独立脚本（例如在 python、php 或 perl 中），然后可选地将表单嵌入到自动创建的 HTML 文档中，以便可以通过浏览器将文档修复/增强发送到相应的脚本，这反过来会将任何修改写回相应的分支。

从长远来看，如果这样的脚本能够支持不同类型的后端（CVS、SVN 或 git），或者至少能够足够通用地实现，从而易于扩展，那将是很酷的。

所以，如果我们能想出一个好的设计，甚至有可能这样的修改会被普遍接受为对 doxygen 本身的贡献，这也会给整个事情更多的曝光和动力。

即使这个想法没有直接实现到一个真正的项目中，看看有多少其他用户真正喜欢这个想法也会很有趣，因此它可能会在 doxygen 问题跟踪器中被提及（https://github.com/ doxygen/doxygen/问题/新）。

编辑：您可能还想查看这篇题为“文档、Git 和 MediaWiki”的文章。

于 2009-05-30T23:34:54.653 回答