c++ - 是否存在用于编辑 doxygen 评论的 "wiki"？

Question

已结束。此问题不符合 Stack Overflow guidelines .它目前不接受答案。

---

我们不允许提出有关书籍、工具、软件库等方面的建议的问题。您可以编辑问题，以便用事实和引用来回答它。

关闭 4 年前。

Improve this question

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

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

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

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

然后，我们开发人员可以不时 merge 此分支以将改进添加到 master 分支，同时开发人员对文档的任何改进最终将在此 web 工具上结束，只需 merge master 分支进入这个特殊的分支。

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

Answer 1

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

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

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

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

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

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

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

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

从长远来看，如果这样的脚本能够支持不同类型的后端(CVS、SVN 或 git)，或者至少实现足够通用，以便于扩展，那就太棒了。

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

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

编辑:您可能还想查看 this标题为 "Documentation, Git and MediaWiki" 的文章.