spieleprogrammierer.de - Forum und Wiki zur Spieleprogrammierung und Spieleentwicklung

Eine automatisch generierte Doku ist halt auch nicht ohne Aufwand. Die Kommentare, die man während der Entwicklung an eine Funktion klatscht, reichen halt nicht annähernd dafür aus eine gute Beschreibung zu sein. Das heißt allerdings nicht das es nicht möglich ist. Man muss sich dann halt nochmal extra darum kümmern. SFML und QT sind zwei Projekte die mir einfallen, die zum Teil eine echt gute generierte Doku haben. Dort sind auch Diagramme, Codebeispiele etc. enthalten. Es ändert vom Aufwand wenig ob man es in den Code schreibt oder in ein extra Dokument.

Ansonsten gibt es halt wie üblich Vor- und Nachteile für beide Seiten. Doku nah am Code hat den Vorteil das sie an die Version gebunden ist und zum Teil auch Refactorings überleben kann bzw. auch schnell mit angepasst werden kann. Im Gegenzug ist es unglaublich hässlich Diagramme, Bilder etc. in Kommentaren unterzubringen. In einem extra Dokument ist es allgemein leichter zu schreiben und übersichtlicher, dafür kann es aber mal schnell veralten und es gibt Bereiche die man vermutlich gar nicht explizit dokumentiert, die automatisch generiert zumindest rudimentär drin wären.

Zitat von »Evrey«

dot, erzähl das mal den WINE-Entwicklern, die sich an undokumentierten Stellen des WinAPIs & Co. seit jeher die Zähne ausbeißen. Oder lies dir mal den Quellcode der STL durch, um die C++-StdLib zu erlernen. Der Quellcode verrät dir ja von sich aus sehr geschickt, wie sich das API z.B. bei Exceptions verhält.

Was genau willst du damit sagen? Die "undokumentierten Stellen der WinAPI", die du da wohl meinst, sind nicht Teil der WinAPI. Das Problem ist, dass es soviel kaputten Code gibt, der vom undokumentierten Verhalten irgendeiner konkreten Windowsversion abhängt (man schaue sich allein z.B. die Geschichte des System32 Ordners an), dass dieses Verhalten unter extrem viel Aufwand aufrecht erhalten wird, damit die kaputte Software weiter laufen kann, obwohl sie kaputt ist. Dass die WINE-Entwickler ebenfalls Software supporten wollen, die schon auf Windows eigentlich nie hätte laufen sollen, ist ihr Problem. Dieses Verhalten zu dokumentieren wäre nicht zielführend, da man dieses Verhalten, das von vorn herein niemals Teil des Interface hätte sein sollen, damit in die API aufnehmen würde und verbindlich weiter supporten müsste. Windows ist mit der MSDN vermutlich das mit Abstand am besten dokumentierte Stück Software, das du irgendwo finden wirst; die STL Spezifikation findest du im C++ Standard und ihr Detailgrad ist bemerkenswert...

Tja faktisch will man mit Wine aber Windows Software zum laufen bringen. Also müssen auch die kaputten Stellen lauffähig sein.