Ich arbeite daran, eine neue und erweiterte Lua API für das Spiel Bitfighter (http://bitfighter.org) zu dokumentieren. Unser Lua-Objektmodell ist eine Teilmenge des C ++ - Objektmodells, und die Methoden, die Lua ausgesetzt sind, die ich dokumentieren muss, sind eine Teilmenge der in C ++ verfügbaren Methoden. Ich möchte nur die für Lua relevanten Elemente dokumentieren und den Rest ignorieren.
Beispielsweise ist das Objekt BfObject das Stammverzeichnis aller Lua-Objekte, befindet sich jedoch selbst in der Mitte der C ++ - Objektstruktur. BfObject hat ungefähr 40 C ++ - Methoden, von denen ungefähr 10 für Lua-Scripter relevant sind. Ich möchte, dass unsere Dokumentation BfObject als Root-Objekt anzeigt und nur diese 10 relevanten Methoden anzeigt. Wir müssten auch seine Kinderobjekte so zeigen, dass die Vererbung von Methoden klar wird.
Im Moment können wir annehmen, dass der gesamte Code in C ++ geschrieben ist.
Eine Idee wäre, die Objekte, die wir dokumentieren wollen, irgendwie so zu markieren, dass ein System wie Doxygen wissen würde, was es zu sehen hat und den Rest ignorieren. Eine andere wäre, den C ++ - Code so vorzuverarbeiten, dass alle nicht relevanten Bits gelöscht werden, und zu dokumentieren, was mit doxygen übrig bleibt. (Ich bin mit diesem Ansatz mit luadoc ziemlich weit gekommen, konnte aber keine Möglichkeit finden, die luadoc-Objekthierarchie zu erstellen.)
Eine Sache, die sich als hilfreich erweisen könnte, ist, dass jede Lua-Objektklasse zusammen mit ihrer Elternklasse konsistent registriert wird.
Es gibt eine wachsende Anzahl von Spielen, die Lua für das Scripting verwenden, und viele von ihnen haben anständige Dokumentation. Hat jemand einen guten Vorschlag, wie man es produziert?
PS Um zu verdeutlichen, bin ich froh, jedes Werkzeug zu benutzen, das die Aufgabe erfüllt - doxygen und luadoc sind nur Beispiele, mit denen ich vertraut bin.
Ich habe eine Lösung gefunden, die zwar nicht ideal ist, aber ziemlich gut funktioniert. Ich habe ein Perl-Skript zusammengebastelt, das den gesamten Bitfighter-Quellcode durchsucht und eine zweite "falsche" Quelle erzeugt, die nur die gewünschten Elemente enthält. Ich kann dann diese sekundäre Quelle durch Doxygen laufen lassen und bekomme ein Ergebnis, das 95% von dem ist, wonach ich suche.
Ich erkläre den Sieg.
Ein Vorteil dieses Ansatzes besteht darin, dass ich den Code auf "natürliche" Weise dokumentieren kann und sich keine Gedanken darüber machen muss, was drin ist und was nicht. Das Skript ist intelligent genug, um es aus der Codestruktur herauszufinden.
Falls jemand daran interessiert ist, steht das Perl-Skript im Bitfighter-Quellarchiv unter Ссылка . Es ist nur zu etwa 80% fertig und es fehlen ein paar sehr wichtige Elemente (wie zum Beispiel das korrekte Anzeigen von Funktionsargumenten), aber die Struktur ist da und ich bin überzeugt, dass der Prozess funktioniert. Das Skript wird mit der Zeit besser.
Die (sehr vorläufigen) Ergebnisse des Prozesses können in Ссылка abgerufen werden. Die Vorlagen wurden kaum verändert, so dass sie sehr "auf Lager" aussehen, aber es zeigt, dass die Dinge mehr oder weniger funktionieren.
Da einige Kommentatoren vorgeschlagen haben, dass es unmöglich ist, mit Doxygen gute Dokumentation zu erstellen, sollte ich beachten, dass fast keine unserer Inline-Dokumente noch hinzugefügt wurde. Um einen Eindruck davon zu bekommen, wie sie aussehen werden, siehe die Teleporter-Klasse. Es ist nicht besonders gut, aber ich denke, es widerlegt die Vorstellung, dass Doxygen immer nutzlose Dokumente produziert.
Mein größtes Bedauern an diesem Punkt ist, dass meine Lösung wirklich eine einmalige Lösung ist und nicht auf das ausgerichtet ist, was ich für ein wachsendes Bedürfnis in der Gemeinschaft halte. Vielleicht werden wir irgendwann einen Weg finden, C ++ und Lua zusammenzuführen, und die Aufgabe, ein verallgemeinertes Dokumentationswerkzeug zu erstellen, wird leichter zu handhaben sein.
PS Sie können sehen, wie das Markup in den ursprünglichen Quelldateien aussieht ... siehe Ссылка , und suchen Sie nach @luaclass
Schließen Sie entweder den Namespace (könnte auch Klasse sein) Ihres C ++ - Codes aus, aber nicht den lua-Code
%Vor%in der doxygen config-Datei oder cherry auswählen, was mit
ausgeschlossen werden soll %Vor%in Ihrem C ++ Code.
Ich persönlich denke, dass das Trennen nach Namespaces besser ist, da es die Trennung in Code + Dokumentation widerspiegelt, was zu einem Namespace-basierten Schema für die Trennung von reinem C ++ von Lua-Bindungen führt.
Trennung über Ausschluss ist wahrscheinlich der am meisten gezielte Ansatz, aber das würde ein zusätzliches Werkzeug beinhalten, um den Code zu analysieren, relevante Lua-Teile zu markieren und den Ausschluss zum Code hinzuzufügen. (Zusätzlich könnten Sie auch spezielle Informationen wie Grafiken separat mit diesem Markup rendern und sie über ein Bild zu Ihrer Dokumentation hinzufügen, zumindest das ist mit Doxygen leicht zu machen.). Da es eine Art von Hinweis auf Lua-Code geben muss, ist das Markup wahrscheinlich nicht zu schwer abzuleiten.
Eine andere Lösung ist die Verwendung von LDoc . Außerdem können Sie C ++ - Kommentare schreiben, die von LDoc analysiert und in die Dokumentation eingefügt werden.
Ein Vorteil ist, dass Sie genau das gleiche Werkzeug haben, um Ihren lua-Code zu dokumentieren. Ein Nachteil ist, dass das Projekt nicht gepflegt wird. Es ist auch nicht möglich, komplexe Objekthierarchien zu dokumentieren, wie der erwähnte Fragesteller.
Ich habe mich selbst für einige kleine Anpassungen gegabelt, was c ++ betrifft. Schauen Sie sich hier um.
Tags und Links c++ lua documentation-generation