spieleprogrammierer.de - Forum und Wiki zur Spieleprogrammierung und Spieleentwicklung

Die Ausgabe von Doxygen kann man auch anpassen.

Naja, es gibt Sphinx. Das ist wohl Dank Python mega hip geworden, aber ich bin mir noch nicht sicher, was ich davon halten soll. Z.B. die Matplotlib-Doku sieht hübsch aus, aber es ist halt alles auf einer Seite, was die Sache enorm unübersichtlich macht:
http://matplotlib.org/api/axes_api.html

Aber für beide Projekte gibt es ja Style-Sheets, vielleicht ist da ja was hübsches dabei. Ich fand Doxygen früher auch eher hässlich, aber seitdem sie es geändert haben (vor ein paar Jahren) fand ich es dann besser.

Bezüglich Sphinx: Ich glaube in dem Fall war es einfach nur eine enorm große Klasse. Das Problem könnte auch sein, dass in matplotlib ungefähr alles in einer großen Klasse ist. Oder dass Python ungetypt ist und man nie weiß, wie jetzt genau die Parameter aussehen müssen und sich deshalb in der Doku nicht zurecht findet. Ich finde es jedenfalls auch nach Monaten noch enorm nervig, die matplotlib-Doku zu lesen. Muss aber keine inhärente Schwäche von Sphinx sein.

Sphinx verfolgt einen anderen Ansatz als Doxygen. Doxygen basiert hauptsächlich auf die Kommentare im Code und generiert eine API-Dokumentation mit fester Struktur. Sphinx basiert auf handgeschriebene Dokumentation, die man selber strukturiert und dabei dokumentierten Code referenzieren kann.

Mein persönlicher Rat: Zerbrich dir gar nicht erst den Kopf, Doku gehört nicht in Kommentare geschrieben...

Zitat von »LetsGo«

Zitat von »dot«

Mein persönlicher Rat: Zerbrich dir gar nicht erst den Kopf, Doku gehört nicht in Kommentare geschrieben...

Würde ich nicht sagen. Die Realität sieht nämlich eher so aus, dass entweder im Code dokumentiert ist, oder gar nicht.

Meiner Erfahrung nach sieht die Realität so aus, dass autogenerierte Doku unwesentlich mehr als eine HTML Ansicht aller Deklarationen ist, die ich nur brauche, weil der eigentliche Source Code durch die ganzen Kommentare völlig unlesbar geworden ist. Eine Library mit autogenerierter Doku von Substanz wäre mir noch nie untergekommen...

Jop finde ich auch am besten. Schön nahe am Code, keine "doppelte" Arbeit und high Level zur Übersicht und für das Gesamtverständnis.

Zitat von »LetsGo«

Zitat von »dot«

Meiner Erfahrung nach sieht die Realität so aus, dass autogenerierte Doku unwesentlich mehr als eine HTML Ansicht aller Deklarationen ist, die ich nur brauche, weil der eigentliche Source Code durch die ganzen Kommentare völlig unlesbar geworden ist. Eine Library mit autogenerierter Doku von Substanz wäre mir noch nie untergekommen...

Ich spreche nicht von autogeneriert, sondern von typischer javaDoc, doxygen Dokumentation.

genau von der spreche ich auch