PrettyOS Dokumentation

Cuervo

Ich habe mal angefangen, eine Funktionsdokumentation für PrettyOS zu schreiben. Leider ist im Nachhinein nicht immer ganz die Funktion der Funktion klar (x'D).

Zu Testzwecken habe ich nur 3 Dateien dokumentiert, ckernel.c, cmos.c und console.c. Kritik erwünscht. Falls alle damit einverstanden sind, werde ich PrettyOS komplett so dokumentieren.

http://prettyos.fanofblitzbasic.de/doctest.pdf

Tobiking2

Ich würde es deutlich schöner finden wenn man das ganze im Quellcode dokumentiert. Da kann man dann mit doxygen auch externe Dokumentationen im html oder pdf Format erstellen. Ich hatte das ja schon mal testweise generiert. Der CDI Teil enthält die Dokumentation nämlich schon. So sieht das dann beispielweise aus: http://85.214.142.202/pretty/doc/structcdi__driver.html

Cuervo

Ich kapiere nicht wirklich, was das soll^^
Das ist unübersichtlich und ausserdem muss ich den Code im Code nicht kommentieren, da sehe ich ja fast sofort, was da passiert!
Dein Dokument ist in 2 Sprachen usw. und für schnelles Nachsehen finde ich meins einfach besser.

Erhard Henkes

@Cuervo: die Wiederholung des Dateinamens kann man vielleicht einsparen, das würde Platz gewinnen.

beselbube

Und wenn man einfach beides macht? Eine komplette Funktionsübersicht auf einem Blick kann viel Wert sein, das ganze im Code ist aber auch sehr hilfreich!

Erhard Henkes

Ich neige ebenfalls zur Auffassung wie 'beselbube'.

Mr X

Ich bin dagegen, im Quellcode zu kommentieren. Das Ergebnis sieht man ja in den CDI-Headern *scheußlich*

Erhard Henkes

Hier ein Beispiel dieser "Scheußlichkeit":

struct cdi_fs_filesystem;
/**
 * Diese Struktur wird fuer jeden Dateisystemtreiber einmal erstellt
 */
struct cdi_fs_driver {
    struct cdi_driver drv;

    /**
     * Neues Dateisystem initialisieren; Diese Funktion muss das root_object in
     * der Dateisystemstruktur eintragen.
     *
     * @return Wenn das Dateisystem erfolgreich initialisiert wurde 1, sonst
     *         0. Falls ein Fehler auftritt, muss das error-Feld in der
     *         Dateisystemstruktur gesetzt werden.
     */
    int (*fs_init)(struct cdi_fs_filesystem* fs);

    /**
     * Dateisystem deinitialisieren
     *
     * @return Wenn das Dateisystem erfolgreich deinitialisiert wurde 1, 0
     *         sonst. Falls ein Fehler auftritt, muss das error-Feld in der
     *         Dateisystemstruktur gesetzt werden.
     */
    int (*fs_destroy)(struct cdi_fs_filesystem* fs);
};

So sähe das wirklich übersichtlicher aus:

struct cdi_fs_filesystem;

// Implement this struct once for each file system driver 
struct cdi_fs_driver 
{
    struct cdi_driver drv;
    int (*fs_init)   (struct cdi_fs_filesystem* fs);
    int (*fs_destroy)(struct cdi_fs_filesystem* fs);
};

Deutsche Kommentare sind im OSDev-bereich weniger hilfreich als englische und zudem meist länger.

TODO für PrettyOS: CDI Kommentare kürzen/übersetzen.

Mr X

TODO die 2.: CDI-Kommentare ent-Doxygenisieren.

Erhard Henkes

Gerade in dem Fall ist es nicht gut gelungen, das ist nicht zu übersehen.

Mr X

und, ehenkes, das obige Beispiel ist noch"schön", verglichen mit dem hier:

cdi-osdep.h:

/**
 * \german
 * Muss fuer jeden CDI-Treiber genau einmal verwendet werden, um ihn bei der
 * CDI-Bibliothek zu registrieren
 *
 * @param name Name des Treibers
 * @param drv Treiberbeschreibung (struct cdi_driver)
 * @param deps Liste von Namen anderer Treiber, von denen der Treiber abhaengt
 * \endgerman
 *
 * \english
 * CDI_DRIVER shall be used exactly once for each CDI driver. It registers
 * the driver with the CDI library.
 *
 * @param name Name of the driver
 * @param drv A driver description (struct cdi_driver)
 * @param deps List of names of other drivers on which this driver depends
 * \endenglish
 */
#define CDI_DRIVER(name, drv, deps...) /* TODO */

/**
 * \german
 * OS-spezifische Daten zu PCI-Geraeten
 * \endgerman
 * \english
 * OS-specific PCI data.
 * \endenglish
 */
typedef struct
{
} cdi_pci_device_osdep;

/**
 * \german
 * OS-spezifische Daten fuer einen ISA-DMA-Zugriff
 * \endgerman
 * \english
 * OS-specific DMA data.
 * \endenglish
 */
typedef struct
{
} cdi_dma_osdep;

Erhard Henkes

wenn das verhältnis zwischen comments und source code größer 1 wird, dann empfindet man das als sehr lästig, müsste ausblendbar sein.

Mr X

Viele IDEs können es auch ausblenden, aber niemand hat ein ernsthaftes Interesse daran, einen Kommentar zu lesen und am besten noch zu verstehen, wenn er voller "@" "\" und sonstigen Tags ist. Das ist wie wenn das Forum alle Beiträge in Code-Form anzeigen würde, also Tags nicht umwandelt.

beselbube

ja das sieht natürlich übertrieben aus - das sind die übereifrigen dokumentierer..

aber kurze kommentare helfen sicherlich. und bei so einfach ausschauendem code müssen es ja keine erklärungen sein, sondern mehr Übersichts/Aufgaben Kommentare.

XanClic

Für mich ist das gar kein Code, für mich sind das Header. Und Header sollten IMO immer der Dokumentation dienen – mir hat man zumindest erzählt, sie sind das Interface zwischen verschiedenen Programmteilen, und zeigen an, welche Funktionen ein anderer Teil bereitstellt. Und nur zu zeigen, wie diese Funktionen heißen, finde ich unzureichend, ich finde es besser, auch gleich (genau!) zu beschreiben, was die tun.

(Nur zu dem „Code-Kommentar-Verhältnis“; der Code steckt sowieso in den von euch zu schreibenden C-Dateien und sicher nicht in diesen Headern)

Mr X

Trotzdem habe ich zumindest den Anspruch, das der Code und die Kommentare lesbar sein müssen. Das ist in den CDI-headern nicht der Fall. Darüber hinaus sehe ich auch bis jetzt keinen Vorteil durch doxygen, ich zumindest neige dazu, selbst im Code zu suchen, als Dokumentationen zu nutzen.

Fazit: Ich bin dagegen, doxygen zu nutzen. Manuell erstellte, externe Doku gerne.

Tobiking2

Wenn man einsprachig kommentiert fallen die german und english tags weg. Das einzige was noch benutzt wird ist @param um einem Parameter zu beschreiben und @return um den Returnwert zu beschreiben. Wenn man zu den Parameter und dem Return Wert nichts schreiben will, bleibt es nen ganz normaler Kommentar, der einfach nur mit /** anfängt und mit */ aufhört. Aber über persönlichen Geschmack zu diskutieren macht wenig Sinn.

Meiner Meinung nach sollte das Erstellen der Dokumentation halt automatisch funktionieren, damit da niemand ständig hinterherrennen muss und die Dokumentation anpasst. Mit den Doxygen Kommentaren im Header kann jeder Entwickler direkt seine Funktionen dokumentieren. Es passiert einfach alles automatisch. Man schreibt einfach einen Kommentar über eine Funktion/Variable/Struct und Doxygen weiß direkt wozu es gehört.

abc.w

Ich bin zwar kein Mitentwickler von PrettyOS und habe kein Mitspracherecht, aber

Tobiking2 schrieb:

Meiner Meinung nach sollte das Erstellen der Dokumentation halt automatisch funktionieren, damit da niemand ständig hinterherrennen muss und die Dokumentation anpasst. Mit den Doxygen Kommentaren im Header kann jeder Entwickler direkt seine Funktionen dokumentieren. Es passiert einfach alles automatisch. Man schreibt einfach einen Kommentar über eine Funktion/Variable/Struct und Doxygen weiß direkt wozu es gehört.

Einmal schreiben, generieren lassen und das war's.

Bezüglich Lesbarkeit: Es werden ja im Code bereits "if()" und "for()" ohne Leerzeichen toleriert, warum sollten die einheitlichen und durchdachten Doxygen-Kommentare nicht lesbar sein

Erhard Henkes

Ich bin zwar kein Mitentwickler von PrettyOS

Wir könnten dich momentan gut brauchen für den Ladevorgang in boot2.asm. Bitte schau dir das mal genauer an.
https://prettyos.svn.sourceforge.net/svnroot/prettyos/trunk/Source/stage2_bootloader/boot2.asm <--- call LoadFile
https://prettyos.svn.sourceforge.net/svnroot/prettyos/trunk/Source/stage2_bootloader/Fat12.inc <--- mehrere HOTFIXES
Das nächste Unheil droht aber bereits.
Wir wollen GRUB nicht gezwungenermaßen.

Erhard Henkes

Meiner Meinung nach sollte das Erstellen der Dokumentation halt automatisch funktionieren, damit da niemand ständig hinterherrennen muss und die Dokumentation anpasst.

Das ist das entscheidende Argument für Doxygen.