Existiert für die Bearbeitung von doxygen Kommentare ein „Wiki“? [geschlossen]

Question

Ich arbeite an einer ziemlich großen Open-Source-RTS-Game-Engine ( Frühling ). Ich habe vor kurzem eine Reihe von neuen C ++ Funktionen aufrufbar von Lua, und frag mir, wie sie am besten dokumentieren und zugleich auch Menschen stimulieren / update-Dokumentation schreiben für viel bestehenden Lua Call- outs.

Also habe ich es dachte, nett sein, wenn ich die Dokumentation schreiben könnte zunächst als doxygen Kommentare in der Nähe der C ++ Funktionen - das ist einfach, da die Funktion Körper genau offensichtlich definiert, was die Funktion tut. Allerdings würde ich die Dokumentation wie von Spiele-Entwicklern verbessert werden, um den Motor verwendet wird, die in der Regel wenig Verständnis für git hat (das VCS wir verwenden) oder C ++.

Daher wäre es ideal, wenn es einen Weg, um automatisch apidocs aus der C ++ Datei zu erzeugen, sondern auch ein Wiki-ähnliche Web-Interface zu haben, ein viel breiteres Publikum zu ermöglichen, die Kommentare zu aktualisieren, fügen Sie Beispiele, usw.

Also ich frage mich, ist gibt es ein Web-Tool, das doxygen Stil Formatierung, Wiki-ähnliche Bearbeitung für diese Äusserungen integriert (vorzugsweise ohne andere Teile der Quelldatei bearbeiten ermöglicht) und git? (Verpflichten, die Kommentare über die Web-Schnittstelle zu einem speziellen Zweig geändert)

Wir Entwickler könnten dann diesen Zweig verschmelzen ab und zu den Verbesserungen an den Master Zweig hinzuzufügen, und zugleich alle Verbesserungen, die von Entwicklern in die Dokumentation würden auf diesem Web-Tool mit nur einer Zusammenführung des Master-Zweiges am Ende in diesem speziellen Zweig.

Ich habe noch nichts gefunden, etwas zweifeln diese spezifische noch vorhanden ist, so dass alle Vorschläge sind willkommen!

Answer 1

Dies ist eine sehr coole Idee in der Tat, und ein paar Jahre hatte ich auch ein sehr starkes Bedürfnis nach etwas ähnlichem. Leider zumindest damals, ich war nicht in der Lage, so etwas zu finden. eine schnelle Suche auf Sourceforge zu tun und auch alles, was mit heute nicht bringen Freshmeat.

Aber ich darüber einig, dass ein solches Wiki Frontend Benutzer beige Dokumentation sehr nützlich sein, würde ich für eine Tatsache wissen, dass so etwas wurde vor kurzem auch in der Gemeinde Lua diskutiert (siehe diese ).

Also, vielleicht können wir die Anforderungen, um festzustellen, mit einem grundlegenden Arbeitsentwurf / Prototyp zu kommen?

Wir hoffen, dies würde sich uns ein solches Projekt mit einem Mindestsatz von Funktionen und dann einfach loslassen in die Wildnis als Open-Source-Projekt (zB auf Source) einzuleiten gehen, so dass andere Benutzer dazu beitragen können.

Idealerweise könnte ein einheitliches Patches verwenden, um Änderungen zu übernehmen, die in einer solchen Art und Weise eingebracht wurden. Außerdem würde es wahrscheinlich sinnvoll, Änderungen zu beschränken sich nur auf das Hinzufügen / Bearbeiten von Kommentaren, statt so dass beliebige Modifikationen des Textes, ist dies wahrscheinlich unter Verwendung eines einfachen Regex umgesetzt werden könnten.

Vielleicht könnte man so etwas umzusetzen, indem eine bestehende (gegründet) Wiki-Software wie mediawiki zu modifizieren. Oder vorzugsweise etwas, der bereits mit git als Backend für Speicherzwecke. Dann würde man in erster Linie braucht für die Doxygen-Stil Kommentare gerecht zu werden und bietet eine einfache Schnittstelle auf es.

einige mehr darüber nachzudenken, Doxygen selbst bietet bereits Support-HTML-Dokumentation zur Erzeugung, so aus dieser Perspektive es tatsächlich interessant sein könnte, um zu sehen, wie Doxygen möglicherweise verlängert werden könnte, so dass es gut mit einem solchen Skript-Backend integriert ist, dass ermöglicht eine einfache Anpassung des Quellcodes Dokumentation eingebettet ist.

Dies würde wahrscheinlich in erster Linie laufen auf ein eigenständiges Skript mit doxygen Bereitstellung (zB in Python, PHP oder Perl) und dann gegebenenfalls einbetten Formulare in der automatisch HTML-Dokumentation erstellt, so dass die Dokumentation Fixes / Vergrößerungen können in das entsprechende Skript gesendet werden über einen Browser, der wiederum alle Änderungen zurück zu einem entsprechenden Zweig schreiben würde.

Auf lange Sicht wäre es cool, wenn ein solches Skript verschiedene Arten von Backends (CVS, SVN oder git) unterstützen würde, oder zumindest allgemein genug umgesetzt werden, so dass es leicht verlängerbar ist.

Wenn wir also mit einem guten Design aufwarten kann, könnte es sogar möglich sein, dass eine solche Änderung würde in der Regel als Beitrag selbst doxygen akzeptiert werden, die auch die ganze Sache viel mehr Aufmerksamkeit und Dynamik geben würde.

Auch wenn die Idee nicht direkt in ein reales Projekt ausbleibt, wäre es interessant, wie viele andere Nutzer tatsächlich, wie die Idee zu sehen, so dass es möglicherweise in der doxygen issue tracker ( https://github.com/doxygen/doxygen/issues/new ).

EDIT: Sie können auch prüfen wollen, dieser Artikel mit dem Titel < a href = "http://morch.com/content/documentation-git-and-mediawiki" rel = "nofollow noreferrer"> "Dokumentation, Git und MediaWiki" .