Existe-t-il un "wiki" pour l'édition des commentaires doxygen?

Question

Je travaille sur un assez gros moteur de jeu RTS open source (Spring). J'ai récemment ajouté un tas de nouvelles fonctions C++ appelables par Lua, et je me demande comment mieux les documenter, et en même temps stimuler les gens à écrire/mettre à jour la documentation pour un lot des appels existants Lua.

Je me suis donc dit que ce serait bien si je pouvais d'abord écrire la documentation en tant que commentaires doxygen près des fonctions C++ - c'est facile parce que le corps de la fonction définit clairement ce que fait la fonction. Cependant, je voudrais que la documentation soit améliorée par les développeurs de jeux utilisant le moteur, qui ont généralement peu de compréhension de git (le VCS que nous utilisons) ou de C++. Par conséquent, il serait idéal s'il y avait un moyen de générer automatiquement des apidocs à partir du fichier C++, mais aussi d'avoir une interface web wiki pour permettre à un public beaucoup plus large de mettre à jour les commentaires, ajouter des exemples, etc. Donc je me demande, existe-t-il un outil web qui intègre la mise en forme de style doxygen, l'édition wiki pour ces commentaires (de préférence sans permettre l'édition d'autres parties du fichier source) et git? (pour commettre les commentaires modifiés via l'interface web vers une branche spéciale)

Nous pourrions alors fusionner cette branche de temps en temps pour ajouter les améliorations à la branche principale, et dans le même temps toutes les améliorations apportées par les développeurs à la La documentation finirait sur cet outil Web avec juste une fusion de la branche principale dans cette branche spéciale.

Je n'ai encore rien trouvé, je doute que quelque chose de spécifique existe encore, donc toutes les suggestions sont les bienvenues!

Answer 1

C'est une très bonne idée en effet, et il y a quelques années j'avais aussi un très fort besoin de quelque chose comme ça. Malheureusement, au moins à l'époque, je n'étais pas capable de trouver quelque chose comme ça. Faire une recherche rapide sur sourceforge et freshmeat n'indique rien de ce qui s'y rapporte aujourd'hui. Mais je suis d'accord qu'une telle interface wiki à la documentation fournie par l'utilisateur serait très utile, je sais pertinemment que quelque chose comme ça a été discuté récemment au sein de la communauté Lua (voir this). Donc, peut-être que nous pouvons déterminer les exigences afin de trouver un brouillon/prototype de travail de base? Heureusement, cela nous permettrait d'initier un tel projet avec un minimum de fonctionnalités, puis de le relâcher dans la nature en tant que projet open source (par exemple sur sourceforge), afin que d'autres utilisateurs puissent y contribuer.

Idéalement, on pourrait utiliser des correctifs unifiés pour appliquer les modifications qui ont été apportées de cette manière. En outre, il serait probablement judicieux de limiter les modifications à l'ajout/l'édition de commentaires, au lieu de permettre des modifications arbitraires de texte, cela pourrait probablement être implémenté en utilisant une simple regex. Peut-être, on pourrait mettre en œuvre quelque chose comme ça en modifiant un logiciel wiki (établi) existant tel que mediawiki. Ou de préférence quelque chose qui utilise déjà git comme backend à des fins de stockage. Ensuite, il faudrait principalement répondre à ces commentaires de style Doxygen et fournir une interface simple en plus.En y réfléchissant encore plus, DoxyGen lui-même fournit déjà un support pour générer de la documentation HTML, donc de ce point de vue, il peut être intéressant de voir comment DoxyGen pourrait être étendu, afin qu'il soit bien intégré avec un tel backend scripté Cela permet une personnalisation facile de la documentation du code source intégré. Cela consisterait probablement principalement à fournir un script autonome avec doxygen (par exemple en python, php ou perl), puis éventuellement à incorporer des formulaires dans la documentation HTML créée automatiquement, de sorte que les correctifs/augmentations de documentation puissent être envoyés aux correspondants. script via un navigateur, qui à son tour écrirait toutes les modifications à une branche correspondante. À long terme, il serait cool qu'un tel script prenne en charge différents types de backends (CVS, SVN ou git), ou au moins soit implémenté assez génériquement, de sorte qu'il soit facilement extensible. Donc, si nous pouvons trouver un bon design, il se pourrait même qu'une telle modification soit généralement acceptée comme une contribution au doxygène lui-même, ce qui donnerait à l'ensemble beaucoup plus d'exposition et de dynamisme.

Même si l'idée ne se matérialise pas directement dans un projet réel, il serait intéressant de voir combien d'autres utilisateurs apprécient réellement l'idée, de sorte qu'elle pourrait éventuellement être mentionnée sur le site Web Doxygen Todo.

EDIT: Vous pouvez également vouloir vérifier this article intitulé "Documentation, Git and MediaWiki".