Welche Doku findet ihr besser?

SeppJ

Vom Aussehen her ganz klar Doxygen. Und DoxyS braucht ja sogar Javascript! Das nervt ungemein, wenn man die Doku lokal liegen hat und NoSccript benutzt. Und das bloß um eine Darstellung zu erzeugen, die imho unübersichtlicher ist als Doxygen.

Was konnte Doxygen nicht parsen? Ich hatte damit noch nie Probleme.

"Nicht parsen" ist nicht das Problem hehe.
Nur bei #defines ist Doxygen etwas komisch.
Auch ein Block mit

#ifndef DOXYGEN_SHOULD_IGNORE_THIS
--- code
#endif

findet nicht immer Beachtung. Manchmal taucht das trotzdem in der Doku auf.

Nexus

Scorcher24 schrieb:

findet nicht immer Beachtung. Manchmal taucht das trotzdem in der Doku auf.

Du musst etwas mit den Präprozessor-Einstellungen des Doxyfiles herumexperimentieren. Ganz intutitiv ist das nicht. Aber für solche Sachen würde ich ohnehin @cond benutzen.

Doxygen ist manchmal etwas verbuggt oder schwer konfigurierbar. Versuche mal, die Dokumentation auf einem dunklen Hintergrund zu erstellen... Viel Spass mit den transparenten Klassendiagrammen. Naja, ich habe ein paar Sachen selbst am Sourcecode angepasst, jetzt geht eigentlich das Meiste. Und für die Diagramme verwende ich mittlerweile Dot (bei dem einige Felder per Default blöderweise auch transparent sind).

Zum Thema: Der DoxyS-Output gefällt mir auch nicht. Wie siehts eigentlich mit der Community dahinter aus? Doxygen hat sich ja inzwischen recht etabliert...

Keine Ahnung bezüglich Community.
Aber Doxygen ist soweit ich das sehen kann, das was am meisten weiterentwickelt wird.

Hast du deine Änderungen btw an den Autor geschickt?

Nexus

Scorcher24 schrieb:

Hast du deine Änderungen btw an den Autor geschickt?

Ja, zumindest die Bugfixes. Die Dot-Erweiterungen könnte ich eigentlich auch mal zu einem SVN-Patch zusammenfassen...

Dravere

@Nexus,
Hast du eigentlich inzwischen eine Lösung dafür herausgefunden?
http://www.c-plusplus.net/forum/265991

Grüssli

Nexus

Ja, das hab ich inzwischen auch eingebaut

Schreib mir eine E-Mail, dann kann ich dir die Binaries schicken. Sourcecode hab ich nicht auf diesem Computer, aber ich nehme an, du willst das eh nicht neu kompilieren.

Ich habe den Vorschlag auch an Dimitri geschickt, vielleicht baut er es eines Tages in eine neue Version ein...

Nexus schrieb:

Scorcher24 schrieb:

Hast du deine Änderungen btw an den Autor geschickt?

Ja, zumindest die Bugfixes. Die Dot-Erweiterungen könnte ich eigentlich auch mal zu einem SVN-Patch zusammenfassen...

Das freut mich wirklich, dass du das auch zurückschickst^^.

edit:
Was auch nicht funktioniert:

/**
 * \defgroup PredefinedColors Predefined Colors
 */

/**
 * \brief Predefined blue color
 * \ingroup PredefinedColors
 */
static const NLColor3f NLCOLOR3F_BLUE(0.0f, 0.0f, 0.8f);

Die Modules-Seite bleibt irgendwie leer.
Bei DoxyS funktioniert das anstandslos.

Typen mit Namespaces im Namen...

Nexus

Scorcher24 schrieb:

Die Modules-Seite bleibt irgendwie leer.

Hm. Ich verwende eigentlich immer

/// @addtogroup MyGroup
/// @{

void Code();

/// @}

Hässlich schrieb:

Typen mit Namespaces im Namen...

Finde ich auch nicht schön. Warum in C++ keine richtigen Namensräume benutzen und Präfixe auf Makros beschränken?

Nexus schrieb:

Scorcher24 schrieb:

Die Modules-Seite bleibt irgendwie leer.

Hm. Ich verwende eigentlich immer
/// @addtogroup MyGroup
/// @{

void Code();

/// @}
Hässlich schrieb:

Typen mit Namespaces im Namen...

Finde ich auch nicht schön. Warum in C++ keine richtigen Namensräume benutzen und Präfixe auf Makros beschränken?

Das obige funktioniert auch nicht.
@prefix
Die Namensräume wurden später eingefügt. Und da existierte schon ein Großteil des Projekts. Dumm, ich weiss. Vielleicht habe ich ja mal Lust das ganze Projekt zu refactorn .

Nexus

Hast du Code() dokumentiert?

Oder probier mal

/// @file
/// @brief Contains Code() function

am Anfang des Dokuments. Das hab ich sowieso immer, weil es eine schöne Übersicht über die Header gibt.

nman

Doxygen, ganz eindeutig. Das andere ist so unlesbar und fürchterlich, dass es aussieht, als wäre die Seite einfach irgendwann kaputtgegangen und als wäre das aufgrund mangelhafter Wartung einfach noch niemandem aufgefallen.

Btw, das Logo ist stark verbesserungsbedürftig.

http://docs.nightlight2d.de/logo.png

Ich nehme zwar an, dass es absichtlich "pixelig" ist, aber das sieht einfach nicht gut aus. Benutz dafür doch mal einen vernünftigen Font und Renderer, das verunstaltet so die ganze Doku-Seite.

Ne war keine Absicht.
Das war nur nen Schnellschuss indem ich das Banner von der Webseite schwarz eingefärbt habe. Habs jetzt neu gemacht.
Eigentlich will ich mich mit sowas momentan nicht so sehr aufhalten -.-^^.
Besser?
Der Font ist nicht dran schuld, im Gegenteil, ich finde den sehr gut.

Nexus schrieb:

Hast du Code() dokumentiert?

Oder probier mal
/// @file
/// @brief Contains Code() function
am Anfang des Dokuments. Das hab ich sowieso immer, weil es eine schöne Übersicht über die Header gibt.

Hat leider nichts gebracht. Scheint wohl an den statics zu liegen. Oder ka..
Wenn ich nen typedef als Beispiel mit rein nehme, dann steht das in der Gruppendoku. Ich glaube ich submitte mal nen Bug :D.

edit:
Jupp, lag am static. Hab das ganze mal in ein .cpp file gepackt und mit extern in Header schon gehts.

Nexus

Warum static in Headerdateien (und nicht gleich inline )?

Abgesehen davon kannst du auf globaler Ebene auch anonyme Namensräume statt static verwenden.

Sollte man nicht sowieso auf konstante, statische öffentliche Datenmember verzichten und stattdessen auf statische, öffentliche Memberfunktionen zurückgreifen?

ntrnt schrieb:

Sollte man nicht sowieso auf konstante, statische öffentliche Datenmember verzichten und stattdessen auf statische, öffentliche Memberfunktionen zurückgreifen?

Siehe ich keinen Vorteil drin, eher nach Nachteil durch den zusätzlichen Funktionsaufruf.

C++ Standard: 3.6.2/1 schrieb:

The order of initialization is unspecified [...] for objects defined in different translation units.

Wenn in einer anderen Übersetzungseinheit also dein Memberobjekt verwendet wird, kannst du nicht davon ausgehen, dass es schon Initialisiert ist.

Wohingegen:

C++ Standard: 6.7/4 schrieb:

Otherwise such an object [lokales, statisches non-POD-Objekt] is initialized the first time control passes through its declaration; such an object is considered initialized upon the completion of its initialization.