是否存在“wiki”编辑doxygen评论？ [英] Does there exist a "wiki" for editing doxygen comments?

问题描述

我正在开发一个相当大的开源RTS游戏引擎（ Spring ）。我最近添加了一些可以由Lua调用的新的C ++函数，我想知道如何最好地记录它们，同时也刺激人们对现有Lua调用的很多写入/更新文档。因此我想如果我可以写文档最初作为doxygen评论附近的C ++函数 - 这很容易，因为函数体明确定义了什么函数。但是，我想让游戏开发人员使用引擎来改进文档，他们通常对git（我们使用的VCS）或C ++有些了解。

它将是理想的，如果有一种方法来自动生成apidocs从C ++文件，但也有一个类似wiki的web界面，允许更广泛的受众更新的评论，添加示例等。

所以我想知道，有没有一个web工具集成doxygen样式格式化，wiki类编辑这些评论（最好不允许编辑任何其他部分的源文件）和git？ （将通过Web界面更改的注释提交到特殊分支）

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

I haven'

解决方案

这是一个非常酷的想法确实，几年前，我也非常需要这样的东西。不幸的是，至少在那时，我找不到类似的东西。快速搜索sourceforge和freshmeat也不会带来任何相关的今天。

但我同意这样的wiki前端用户提供的文档将是非常有用的，我知道一个事实，这样的东西最近也在Lua社区中讨论（请参见这个）。

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

$ b $希望这将使我们开始这样一个项目与一个最小的功能，然后简单地释放它作为一个开源项目（例如在sourceforge），以便其他用户可以贡献它的野生。

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

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

还有一些，DoxyGen本身已经提供支持生成HTML文档，所以从这个角度看，可能真的很有趣的是，DoxyGen如何可能被扩展，以便它与这样一个脚本化的后端很好地集成，允许嵌入式源代码文档的轻松自定义。

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

从长远来看，如果这样的脚本将支持不同类型的后端（CVS，SVN或git），或者至少是一般性地实现，以便它是容易扩展的。

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

即使这个想法没有直接实现到一个真正的项目，很有趣的是看到有多少其他用户实际上喜欢这个想法，所以它可能会在 Doxygen Todo 网站。

编辑：您还可以查看这篇标题为文档，Git和MediaWiki。

I'm working on a fairly big open source RTS game engine (Spring). I recently added a bunch of new C++ functions callable by Lua, and am wondering how to best document them, and at the same time also stimulate people to write/update documentation for a lot of existing Lua call-outs.

So I figured it may be nice if I could write the documentation initially as doxygen comments near the C++ functions - this is easy because the function body obviously defines exactly what the function does. However, I would like the documentation to be improved by game developers using the engine, who generally have little understanding of git (the VCS we use) or C++.

Hence, it would be ideal if there was a way to automatically generate apidocs from the C++ file, but also to have a wiki-like web interface to allow a much wider audience to update the comments, add examples, etc.

So I'm wondering, does there exist a web tool which integrates doxygen style formatting, wiki-like editing for those comments (preferably without allowing editing any other parts of the source file) and git? (to commit the comments changed through the web interface to a special branch)

We developers could then merge this branch every now and then to add the improvements to the master branch, and at the same time any improvements by developers to the documentation would end up on this web tool with just a merge of the master branch into this special branch.

I haven't found anything yet, doubt something this specific exists yet, so any suggestions are welcome!

解决方案

This is a very cool idea indeed, and a couple of years ago I also had a very strong need for something like that. Unfortunately, at least back then, I wasn't able to find something like that. Doing a quick search on sourceforge and freshmeat also doesn't bring up anything related today.

But I agree that such a wiki frontend to user-contributed documentation would be very useful, I know for a fact that something like this was recently being discussed also within the Lua community (see this).

So, maybe we can determine the requirements in order to come up with a basic working draft/prototype?

Hopefully, this would get us going to initiate such a project with a minimum set of features and then simply release it into the wild as an open source project (e.g. on sourceforge), so that other users can contribute to it.

Ideally, one could use unified patches to apply changes that were contributed in such a fashion. Also, it would probably make sense to restrict modifications only to adding/editing comments, instead of allowing arbitrary modifications of text, this could probably be implemented by using a simple regex.

Maybe, one could implement something like that by modifying an existing (established) wiki software such as mediawiki. Or preferably something that's already using git as a backend for storage purposes. Then, one would mainly need to cater for those Doxygen-style comments, and provide a simple interface on top of it.

Thinking about it some more, DoxyGen itself already provides support for generating HTML documentation, so from that perspective it might actually be interesting to see, how DoxyGen could possibly be extended, so that it is well integrated with such a scripted backend that allows for easy customization of embedded source code documentation.

This would probably mainly boil down to providing a standalone script with doxygen (e.g. in python, php or perl) and then optionally embed forms in the automatically created HTML documentation, so that documentation fixes/augmentations can be sent to the corresponding script via a browser, which in turn would write any modifications back to a corresponding branch.

In the long term, it would be cool if such a script would support different types of backends (CVS, SVN or git), or at least be implemented generically enough, so that it is easily extendsible.

So, if we can come up with a good design, it might even be possible that such a modification would be generally accepted as a contribution to doxygen itself, which would also give the whole thing much more exposure and momentum.

Even if the idea doesn't directly materialize into a real project, it would be interesting to see how many other users actually like the idea, so that it could possibly be mentioned on the Doxygen Todo website.

EDIT: You may also want to check out this article titled "Documentation, Git and MediaWiki".

这篇关于是否存在“wiki”编辑doxygen评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！