Esiste un "wiki" per modificare i commenti di doxygen?

Question

Sto lavorando a un motore di gioco RTS open source abbastanza grande (Spring). Recentemente ho aggiunto un sacco di nuove funzioni C++ richiamabili da Lua e mi sto chiedendo come documentarle al meglio, e allo stesso tempo stimolare le persone a scrivere/aggiornare la documentazione per un sacco di callout Lua esistenti.

Quindi ho pensato che potrebbe essere bello se potessi scrivere la documentazione inizialmente come commenti di ossigeno vicino alle funzioni del C++ - questo è facile perché il corpo della funzione definisce chiaramente esattamente ciò che fa la funzione. Tuttavia, vorrei che la documentazione fosse migliorata dagli sviluppatori di giochi che utilizzano il motore, che generalmente hanno poca conoscenza di git (il VCS che usiamo) o C++.

Quindi, sarebbe ideale se esistesse un modo per generare automaticamente apidoc dal file C++, ma anche di avere un'interfaccia web di tipo wiki per consentire ad un pubblico molto più ampio di aggiornare i commenti, aggiungere esempi, ecc.

Quindi mi chiedo, esiste uno strumento web che integra la formattazione in stile doxygen, la modifica di tipo wiki per quei commenti (preferibilmente senza consentire la modifica di altre parti del file sorgente) e git? (per inviare i commenti modificati tramite l'interfaccia web a un ramo speciale)

Gli sviluppatori possono quindi unire questo ramo ogni tanto per aggiungere i miglioramenti al ramo principale e allo stesso tempo eventuali miglioramenti degli sviluppatori al la documentazione finirebbe su questo strumento web con una semplice fusione del ramo master in questo ramo speciale.

Non ho ancora trovato nulla, dubito di qualcosa che questo specifico esiste ancora, quindi qualsiasi suggerimento è benvenuto!

Answer 1

Questa è davvero una bella idea, e un paio di anni fa avevo anche un forte bisogno di qualcosa del genere. Sfortunatamente, almeno allora, non ero in grado di trovare qualcosa del genere. Fare una rapida ricerca su sourceforge e freshmeat non fa apparire nulla di simile oggi.

Ma sono d'accordo sul fatto che un tale frontend wiki alla documentazione fornita dagli utenti sarebbe molto utile, so per certo che qualcosa di simile è stato discusso di recente anche all'interno della comunità Lua (vedi this).

Quindi, forse possiamo determinare i requisiti per elaborare una bozza/prototipo di lavoro di base?

Speriamo che questo ci consenta di avviare un progetto di questo tipo con un set minimo di funzionalità e quindi di rilasciarlo come un progetto open source (ad esempio su sourceforge), in modo che altri utenti possano contribuirvi.

Idealmente, è possibile utilizzare patch unificate per applicare le modifiche apportate in questo modo. Inoltre, probabilmente avrebbe senso limitare le modifiche solo all'aggiunta/modifica dei commenti, invece di consentire modifiche arbitrarie del testo, questo potrebbe probabilmente essere implementato usando una semplice espressione regolare.

Forse, si potrebbe implementare qualcosa di simile modificando un software wiki esistente (stabilito) come mediawiki. O preferibilmente qualcosa che sta già usando git come back-end per scopi di archiviazione. Quindi, uno dovrebbe principalmente soddisfare quei commenti stile Doxygen e fornire una semplice interfaccia su di esso.

Pensando ancora un po ', Doxygen stesso fornisce già supporto per generare documentazione HTML, quindi da questo punto di vista può in realtà essere interessante per visualizzare come doxygen potrebbe essere esteso, in modo che sia ben integrato con una tale backend script che consente una facile personalizzazione della documentazione del codice sorgente incorporato.

Questo probabilmente si limiterà principalmente a fornire uno script autonomo con doxygen (ad esempio in python, php o perl) e quindi facoltativamente incorporare i moduli nella documentazione HTML creata automaticamente, in modo che la documentazione correzioni/aumenti possa essere inviata al corrispondente script tramite un browser, che a sua volta dovrebbe riportare le modifiche su un ramo corrispondente.

A lungo termine, sarebbe bello se un tale script supportasse diversi tipi di backend (CVS, SVN o git), o almeno fosse implementato genericamente abbastanza, in modo che fosse facilmente estendibile.

Quindi, se possiamo trovare un buon progetto, potrebbe anche essere possibile che tale modifica sia generalmente accettata come un contributo al doxygen stesso, il che darebbe all'intero oggetto molta più esposizione e quantità di moto.

Anche se l'idea non si concretizza direttamente in un progetto reale, sarebbe interessante vedere quanti altri utenti apprezzano l'idea, in modo che possa essere menzionata sul sito Web Doxygen Todo.

MODIFICA: È inoltre possibile controllare l'articolo this"Documentation, Git and MediaWiki".