PrettyOS Dokumentation



  • 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;
    

  • Mod

    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.



  • 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.



  • 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.



  • 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)



  • 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.



  • 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.



  • 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 😕 😉


  • Mod

    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.


  • Mod

    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.


Anmelden zum Antworten