¿Existe un "wiki" para editar los comentarios de doxygen?

Question

Estoy trabajando en un motor de juego RTS de código abierto bastante grande (Spring). Recientemente agregué un montón de nuevas funciones de C++ llamables por Lua, y me pregunto cómo es mejor documentarlas, y al mismo tiempo también estimular a la gente a escribir/actualizar la documentación para mucho de Lua llamadas existentes.

Así que pensé que sería bueno si pudiera escribir la documentación inicialmente como comentarios doxygen cerca de las funciones de C++, esto es fácil porque el cuerpo de la función obviamente define exactamente lo que hace la función. Sin embargo, me gustaría que la documentación sea mejorada por los desarrolladores de juegos que usan el motor, que generalmente tienen poca comprensión de git (el VCS que usamos) o C++.

Por lo tanto, sería ideal si hubiera una manera de generar apidocs automáticamente desde el archivo C++, pero también tener una interfaz web tipo wiki que permita a un público mucho más amplio actualizar los comentarios, agregar ejemplos, etc.

Entonces, me pregunto, ¿existe una herramienta web que integre el formato de estilo doxygen, edición tipo wiki para esos comentarios (preferiblemente sin permitir la edición de otras partes del archivo fuente) y git? (para enviar los comentarios cambiados a través de la interfaz web a una sucursal especial)

Nosotros los desarrolladores podríamos fusionar esta rama de vez en cuando para agregar las mejoras a la rama principal, y al mismo tiempo cualquier mejora de los desarrolladores a la la documentación terminaría en esta herramienta web con solo una fusión de la rama principal en esta rama especial.

No he encontrado nada aún, dudo de que algo específico exista todavía, por lo que cualquier sugerencia es bienvenida!

Answer 1

Esta es una idea realmente genial, y hace un par de años también tenía una gran necesidad de algo así. Lamentablemente, al menos en aquel entonces, no pude encontrar algo así. Hacer una búsqueda rápida en sourceforge y freshmeat tampoco trae nada relacionado hoy.

Pero estoy de acuerdo en que una interfaz wiki de este tipo para la documentación aportada por el usuario sería muy útil, sé de hecho que algo así también se discutió recientemente dentro de la comunidad Lua (ver this).

Entonces, ¿tal vez podamos determinar los requisitos para elaborar un borrador/prototipo básico de trabajo?

Afortunadamente, esto nos llevaría a iniciar un proyecto con un conjunto mínimo de características y luego simplemente lanzarlo a la naturaleza como un proyecto de código abierto (por ejemplo, en sourceforge), para que otros usuarios puedan contribuir.

Idealmente, uno podría usar parches unificados para aplicar los cambios que se contribuyeron de esa manera. Además, probablemente tendría sentido restringir modificaciones solo para agregar/editar comentarios, en lugar de permitir modificaciones arbitrarias de texto, esto probablemente podría implementarse usando una expresión regular simple.

Tal vez, uno podría implementar algo así al modificar un software wiki existente (establecido) como mediawiki. O preferiblemente, algo que ya está usando git como un backend para propósitos de almacenamiento. Entonces, uno necesitaría principalmente atender esos comentarios al estilo de Doxygen, y proporcionar una interfaz simple en la parte superior.

Pensando en ello un poco más, DoxyGen ya proporciona soporte para generar documentación HTML, por lo que desde esa perspectiva podría ser interesante ver cómo DoxyGen podría extenderse, para que esté bien integrado con un back-end con scripts que permite una fácil personalización de la documentación del código fuente incrustado.

Esto probablemente se reduciría principalmente a proporcionar un script independiente con doxygen (por ejemplo, en python, php o perl) y opcionalmente incrustar formularios en la documentación HTML creada automáticamente, para que la documentación corrija/aumente se pueda enviar a la correspondiente secuencia de comandos a través de un navegador, que a su vez escribiría cualquier modificación a la rama correspondiente.

A largo plazo, sería genial si tal script soportara diferentes tipos de backends (CVS, SVN o git), o al menos se implementara genéricamente, de modo que sea fácilmente extensible.

Por lo tanto, si podemos encontrar un buen diseño, incluso podría ser posible que una modificación de este tipo se acepte generalmente como una contribución al propio doxygen, lo que también daría a todo mucho más exposición e impulso.

Incluso si la idea no se materializa directamente en un proyecto real, sería interesante ver a cuántos otros usuarios realmente les gusta la idea, por lo que posiblemente se pueda mencionar en el sitio web Doxygen Todo.

EDITAR: Quizás desee comprobar this artículo titulado "Documentation, Git and MediaWiki".