Quelltext und Dokumentation trennen?

Fusel.Factor

Hallo liebes Forum,

ich Frage mich gerade wie man am sinnvollsten dokumentiert und ob man den Quelltext von der Dokumentation trennen sollte. Bis jetzt habe ich ein paar Tools wie Doxygen ausporbiert, aber irgendwie finde ich sieht der Quelltext dann überladen aus. Die Alternative wäre ja von Anfang 2 Dokumente zu haben. Einmal den Quelltext und eine Dokumentation. Das Problem dabei ist dann aber, dass es leicht passieren kann, dass ( aus Faulheit z.B. ) eines von beiden in der Version hinterherhängt. Also meine Frage, besonders an die Leute die schon ein paar Järchen dabei sind und größere Projekte durchgezogen haben, wie dokumentiert man am besten?

Artchi

Veraltete Doku kannst du auch mit nur einer Quelle (Doku von Source getrennt) haben. Das hat nichts mit zu tun, ob du zwei Quellen (Source und Doku getrennt). Denn ob eine Doku veraltet ist, kannst du in beiden Fällen nur rausfinden, in dem man die generierte Doku liest.

Die Doku vom Code trennen geht mit Doxygen recht einfach, wenn man sich an die Warnings von Doxygen hält. Sobald ein Typ, Funktion oder Paramter nicht dokumentiert ist, spuckt Doxygen eine Warning aus. Und dann kann man das entsprechend nachholen. Ob man die Doku vom Source trennt, ist eine Gewohnheitssache. Ich pers. dokumentiere die API direkt in den Headern. Ausschweifenden Prosa (Konzepte, Tutorial usw.) lagere ich dagegen in Textdateien aus, die Doxygen gleich mit ab arbeiten kann.

Julian__

Artchi schrieb:

Ausschweifenden Prosa (Konzepte, Tutorial usw.) lagere ich dagegen in Textdateien aus, die Doxygen gleich mit ab arbeiten kann.

das ist cool, gibts speziell dazu vllt. nen link oder sowas?
nicht zu doxygen ganz allgemein, sondern zu diesem verfahren.

mfg,
julian

Julian__ schrieb:

Artchi schrieb:

Ausschweifenden Prosa (Konzepte, Tutorial usw.) lagere ich dagegen in Textdateien aus, die Doxygen gleich mit ab arbeiten kann.

das ist cool, gibts speziell dazu vllt. nen link oder sowas?
nicht zu doxygen ganz allgemein, sondern zu diesem verfahren.

mfg,
julian

Klar steht im Handbuch von Doxygen, einfach mal lesen.

Fusel.Factor

Ich habe mich jetzt ein bischen intensiver mit Doxygen beschäftigt und finde es doch sehr gut. Eine Kleinigkeit stört mich jedoch. Die Typen der Parameter einer Funktion werden auf ihre Dekleration verlinkt. Dies gilt allerdings nicht für Template Parameter.

Bsp:

enum Enum 
{
    val1,
    val2
}

template< Enum T >
void Foo( Bar arg )
{
}

In der Dolumentaion könnte ich jetzt auf Bar klicken und würde dann dahin geleitet werden, für Enum gilt das leider nicht. Habe ich es falsch gemacht, oder muss ich eine manuelle Verlinkung machen?