Programmcode Dokumentieren

Als Vorbild für meine Dokumentaion hab ich speziell diesen Teil der 
Website genommen. Somit würe sich das ganze wohl eher "Referenz" als 
"Dokumentation" nennen.....

http://www.nongnu.org/avr-libc/user-manual/modules.html

Hallo Markus,

das kannst du mit doxygen machen.
Deine Sourcefiles mußt du entprechend vorbereiten und dann mit doxygen 
"compilieren."

Nachfolgend noch einmal ein hilfreicher Link.
[[Beitrag "Automatisches Kommentieren von Code"]]

Gruss Nobbie

Das ist nicht was ich meine ,aber trotzdem Danke ;)

Die Quellcode Kommentare sind alle schon geschrieben.

Ich meine eine Handschriftliche Dokumentation über das ganze Programm.
Z.b. das erst ein Flussdiagramm das die Hauptschleife beschreibt rein 
kommt, danach die einzelnen Bibliotheken beschrieben werden und die 
Funktionen im einzelnene.

Eine Softwaredokumentation eben, die leicht verständlich und nicht 
unnötig überlastet ist .....


Vielleicht ist die Frage auch bisschen blöd fürs Forum. Sollte 
eigentlich jedem entwickler seine eigene Sache sein wie er Dokumentiert, 
aber evtl. hat ja doch jemand schon erfahrungen damit gesammelt.....

Eben das macht Doxygen doch.
Nur eben das deine Komentare eine etwas andere Form haben.
Der Inhalt ist der gleiche.
Sogar flussdiagramme werden automatisch gezeichnet.

Markus wrote:

> Vielleicht ist die Frage auch bisschen blöd fürs Forum. Sollte
> eigentlich jedem entwickler seine eigene Sache sein wie er Dokumentiert,
> aber evtl. hat ja doch jemand schon erfahrungen damit gesammelt.....

Nein, du siehst das schon richtig. Wie du an den Antworten siehst, 
meinen viele Entwickler, eine Beschreibung der Funktionen und Module 
reiche voellig aus. Leider fehlt dann bei dieser Art der Dokumentation 
voellig die Beschreibung der Zusammenhaenge, der grosse Ueberblick 
sozusagen. Schreibe das ganze wirklich so, als wolltest du Jemandem 
Stueck fuer Stueck erklaeren, was du da kreiert hast. Am Besten faengst 
du damit an, was das Programm eigentlich tut - sollte man nicht glauben, 
aber das wird gerne vergessen.

>Leider fehlt dann bei dieser Art der Dokumentation
>voellig die Beschreibung der Zusammenhaenge

das funktioniert, wenn du eine lib geschrieben hast.
aber du willst ja ein programm dokumentieren.

auch wenn das nicht so klar wird, ich wollte peter zustimmen :)

>Im Rahmen meines Technikerprojektes ist es notwendig, den Programmcode
>meiner Microcontroller Lösung zu dokumentieren. Es soll also eine Art
>"Bedienungsanleitung" zu der von mir geschriebenen Software entstehen.

Das kannst du ja machen. Nur musst du dich entscheiden, ob das eine 
Bedienungsanleitung für den Benutzer des Gerätes bzw, der Software wird 
(der sich überhaupt nicht für Funktionsaufrufe oder Parameter 
interessiert), oder eine Softwaredokumentation bzw. 
Schnittstellendokumenation des Quellcodes.

Für ersteres nimmst du das Textprogramm deines Vertrauens, und schreibst 
einen schönen Text mit vielen Bildern.

Für lezteres empfiehlt sich das, was hier schon vorgeschlagen wurde: 
Doxygen. Die avr-libc hast du ja schon selber als Beipiel genommen. 
Schau dir auch mal die Online-Doku zur avrlib an:

http://www.mil.ufl.edu/~chrisarnold/components/microcontrollerBoard/AVR/avrlib/docs/html/index.html

Fast alles, was du da siehst, wurde automatisch aus dem Quellcode 
erzeugt. Natürlich muß das da auch alles irgendwo drinstehen.

Oliver

Markus wrote:
> Ich meine eine Handschriftliche Dokumentation über das ganze Programm.
> Z.b. das erst ein Flussdiagramm das die Hauptschleife beschreibt rein
> kommt, danach die einzelnen Bibliotheken beschrieben werden und die
> Funktionen im einzelnene.
Das ist in 99% der Fälle unsinnig. Überleg mal: Du hast einen Quelltext 
vor dir liegen. In den schreibst du Kommentare, damit sich der Quelltext 
sauber und leicht lesen und verstehen lässt. Dann kritzelst du nochmal 
alles in Form von Diagrammen. Und jetzt liest du aufm Monitor den 
Quelltext und blätterst gleichzeitig in deiner Diagrammschrift rum... 
Spätestens bei der nächsten Änderung des Quelltextes passt nichts davon 
mehr zusammen :-D

Also ernsthaft: Guter Programmtext lässt sich auch gut lesen. Als 
Daumenregel kann man sagen: Wird die Dokumentation des Quelltextes (also 
die 'Diagrammbeschreibung', damit meine ich nicht die Beschreibung 
eines API) länger als der Quelltext selbst, dann ist fast immer der 
Quelltext verbockt (z.B. unnötig kompliziert formuliert usw.).