是否存在“维基”用于编辑doxygen评论？ [英] Does there exist a "wiki" for editing doxygen comments?
问题描述
我正在开发一个相当大的开源RTS游戏引擎（ Spring ）。我最近添加了一些Lua调用的新的C ++函数，并且想知道如何最好地记录它们，同时也刺激人们为现有Lua调用的很多编写/更新文档，出来。
所以我认为如果我最初可以用C ++函数附近的doxygen来编写文档可能会很好 - 这很容易，因为函数体显然定义了什么该功能是。然而，我希望游戏开发人员使用引擎来改进文档，引擎通常对git（我们使用的VCS）或C ++几乎不了解。
因此，如果有办法从C ++文件自动生成apidocs，还要有一个类似维基的Web界面，以便更广泛的受众更新评论，添加示例等，这将是理想的。
所以我想知道，是否存在一个网页工具，它集成了doxygen样式格式，wiki类似的编辑（最好不要编辑源文件的其他部分）和git？ （将通过Web界面更改的注释提交到一个特殊的分支）
然后我们开发人员可以合并这个分支，然后将这些改进添加到主分支，同时，开发人员对文档的任何改进将最终都归结于这个网络工具，只需将主分支合并到这个特殊的分支中。
我避风港没有找到任何东西，怀疑这个具体存在的东西，所以任何建议都是欢迎的！
几年前，我也非常需要这样的东西。不幸的是，至少在此之后，我无法找到类似的东西。对sourceforge和freshmeat进行快速搜索也不会带来任何与今天相关的东西。
但是我同意这样一个wiki前端用户贡献的文档将是非常有用的我知道一个这样的事实最近也在Lua社区内讨论过（见这个 希望这将使我们以最小的功能集开始这样一个项目，然后简单地将其作为一个开源项目（例如在sourceforge中）发布到野外，以便其他用户可以贡献它 理想情况下，可以使用统一的补丁来应用以这种方式贡献的更改。另外，将修改限制在仅添加/编辑注释可能是有意义的，而不是允许任意修改文本，这可能会通过使用一个简单的正则表达式来实现。 也许，可以通过修改现有的（已建立的）维基软件（如mediawiki）来实现这一点。或者最好是已经使用git作为后端进行存储的东西。那么，主要是需要满足那些Doxygen风格的评论，并提供一个简单的界面。 还有更多的想法，DoxyGen本身已经提供支持生成HTML文档，所以从这个角度来看，可能会看到DoxyGen如何被扩展，因此它可以很好地集成到这样一个脚本化的后端，这样可以轻松地自定义嵌入式源代码文档。 这可能主要是为了提供一个独立的脚本与doxygen（例如在python，php或perl），然后可选地将表单嵌入到自动创建的HTML文档中，以便文档修复/ augmentations可以通过浏览器发送到相应的脚本，浏览器又会将任何修改写回相应的分支。 从长远来看，这将是很酷的如果这样的脚本将支持不同类型的后端（CVS，SVN或git），或者在l东方一般实施，所以它很容易扩展。 所以，如果我们可以想出一个好的设计，甚至可能这样的修改被普遍接受为对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". 这篇关于是否存在“维基”用于编辑doxygen评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
