Wie erstellt man Dokumentationen zu einem vorhandenden Autoit Script?

Wie wär's wenn du einen Texteditor deiner Wahl nimmst und drauf los schreibst?

Schönen guten Abend
Ich versuche es mal so allgemein wie möglich zu halten. Im Grunde kann eine Dokumentation verschieden ausfallen. Der Sinn und Zweck ist auf jeden Fall z.B. die Verwendung eines Programmes den Benutzer beizubringen, oder die Funktionen / Klassen (bezogen auf C++ u. ähnliches) in einer UDF (oder auch DLL) zu dokumentieren damit der Programmierer diese verwenden kann. Alle drei Möglichkeiten (Programm, UDF / Klassenbibliothek und DLL’s) werde ich hier einmal erläutern. Für Fehler und deren Folgen übernehme ich keine Haftung.

User Defined Functions:
Hier im Forum wird hauptsächlich mit *.au3 Files gehandelt welche eindeutig in der Rohversion vorliegen. Dabei hat jeder Zugriff auf den Sourcecode und kann diesen nach Belieben verändern. Dies ist auch in anderen Programmiersprachen wie C++ der Fall. Nur dort werden Funktionsansammlungen anderes benannt. Ich weiß nicht ob meine Informationsquelle zuverlässig ist, aber ich glaube sie heißen dort „Header“ oder auch „Klassenbibliotheken“. Zwischen Unterschiede lässt sich streiten und ist definitiv nicht das Thema meines Textes. Jedenfalls, so finde ich, sind diese am leichtesten zu dokumentieren weil die Beschreibungen direkt als Kommentar im Sourcecode hinterlegt werden kann. Dabei sollten folgende Dinge beachtet werden:
- Zuerst muss eine vollständige Beschreibung der Funktion vorliegen. Beantworte einfach dazu die Frage „Was macht diese Funktion?“ und du hast deine Arbeit getan. Wichtig ist vor allem dass entweder in der Sprache deiner Zielgruppe geschrieben wird oder in Englisch. Alles andere wäre nur unsinnig.
- Nun kommen die Parameter dran. Beschreibe jeden Parameter einzeln! Die Frage „Welche Werte nimmt der Parameter entgegen und warum?“ hilft dir dabei. Halte dich dabei so kurz wie möglich (Besonders bei langen Funktionen).
- Zuletzt wird dokumentiert welchen Wert die Funktion zurückgibt und wie dieser weiterverarbeitet werden kann.
Die oberen genannten Punkte stellen dabei nur eine Mindestanforderung dar. Gerne dürfen selber weitere Punkte hinzugefügt werden. Auch je nach Programmiersprache variiert dieses. Beispielsweise muss für eine Klasse in C++ noch zusätzlich die Klasse beschrieben werden. Oder auch Konstanten müssen für ihren Zweck erläutert werden. AutoIt stellt zum Glück einen Funktionsheader zur Verfügung der auch in allen Standard UDF’s verwendet wird:

; #FUNCTION# ====================================================================================================================
; Name ..........: function
; Description ...:
; Syntax ........: function()
; Parameters ....:
; Return values .: None
; Author ........: Your Name
; Modified ......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......: No
; ===============================================================================================================================

Programme:
Manchmal möchte Mann eine Dokumentation schreiben weil er befürchtet dass Frau mit dem komplexen System nicht klar kommt. Meistens sind diese auch tatsächlich hilfreich. Zuerst sollte man sich überlegen in welchen Sprachen man seine Dokumentation schreibt (vorzugsweise in der, die auch das Programm verwendet) und welches Format man verwendet. Mit Format meine ich nicht die üblichen Dateiendungen wie *.html oder *.pdf etc. sondern die Form bzw. den Stil der Dokumentation. Man kann es selbstverständlich als offline Website aufbauen oder als einfache PDF hinterlegen, muss man aber nicht. Ein klassisches Dateiformat wäre z.B. *.chm welche Windows automatisch seinen Hilfedatei Look verpasst. Andere Alternativen wäre beispielsweise ein externes Programm zu schreiben welches die einzelnen Texte formatiert anzeigt. So lassen sich auch ganz individuelle Bedienelemente hinzufügen. Jedenfalls sollte eine allgemeine Beschreibung des Programmes vorhanden sein. Eine einfache und simple Frage wäre: „Was macht das Programm?“ Natürlich sollte man den Text ein wenig ausschmücken und rudimentäre Werbebanner hinzufügen. Weitere wichtige Punkte sind Beschreibungen zu allen Bedienungselementen in dem selbst geschriebenen Programm. Weiteres lässt sich ergänzen.

DLL’s:
Im Grunde werden diese genauso dokumentiert wie UDF’s nur mit dem Unterschied, dass dies in einer externen Datei geschehen muss, weil der Sourcecode für den Programmierer nicht einsehbar ist. Auch hier müssen wieder die Mindestanforderungen erfüllt werden. Dabei sollten aber auch wirklich nur Funktionen dokumentiert werden, die relevant für die Programmierer sind, welche die DLL später verwenden. Meist gibt es zu den DLL’s auch Header (meist in C oder C++ der Fall) wo auch die Beschreibungen hinterlegt werden können. Allerdings gehe ich dazu nicht weiter ein weil man meist keine Dokumentationen zu DLL’s schreibt sondern welche zu vorhanden DLL’s sucht.

Ich hoffe ich konnte dir etwas weiterhelfen. Falls du Fragen hast oder etwas unklar ist, dann sag mir Bescheid. Wie man sieht bin ich in voller Schreiblust.
~ Make

Für PDF Dateien verwende ich Microsoft Word 2010.
Die *.docx Files lassen sich einfach in *.pdf Files exportieren.
Für *.chm Files habe ich mir das Programm BookME gedownloadet.
Es wird kostenlos angeboten. Den Downloadlink habe ich nicht mehr.
Für *.html Files (um diese schnell zu erstellen) verwende ich einen Editor.
Diese haben auch einen speziellen Namen der mir aber entfallen ist.
~ Make

Für solch einen UDF-Header einfach in die Zeile klicken wo dein "Func Bla(..)" steht und dann Ctrl+Alt+H drücken
(Alternativ im Tools-Menü auswählen)

Es gibt dafür auch ein sehr schönes Programm: https://autoit.de/index.php?page=Thread&threadID=18191
Edit: bitte keine (unnötige) Leichenschändung betreiben, der obige Thread ist so gut wie er ist

lg
M

Wie gesagt, wie Dokumentationen wie z.B. die Hilfedatei von AutoIt erstelle ich mit BookME.
Selbstverständlich muss Text noch selber getippt werden, aber das Design wird als *.html oder auch *.chm Datei generiert.
Zudem bietet das Programm auch die Möglichkeit selber Vorlagen zu erstellen. So brauchst du diese nur einmal zu erstellen und den Text nur noch hinein schreiben.
Im Anhang ein einfaches Beispiel

Zur FF.au3 Dokumentation:
Die eigentliche Beschreibung ist per Hand gemacht, wobei diese wiederrum nur Templates für die Dateien auf dem Web-Server sind.
Die Funktionsaufrufe und die Kurzbeschreibungen werden aus der UDF erstellt und auf den Server geschoben.
Diese werden dann per PHP in die Dateien eingefügt, ebenso die Beispiele, die gleichzeitig noch mit Syntax-Highlighting versehen werden. (Die Beispiele sind die gleichen die man auch downloaden kann)

Also ein bisschen Arbeit ist schon noch nötig, außer man schreibt die eigentliche Beschreibung auch noch in die UDF und läßt dann alles daraus genererieren.
Dort könnte man dann noch etwas Vorformatierung z.B mit reStructuredText oder Ähnlichem vornehmen.

Oder man verwendet etwas davon:
https://de.wikipedia.org/wiki/Software-…tationswerkzeug
ist zwar alles nicht für AutoIt gedacht, könnte man aber dennoch verwenden, ohne das Rad wieder von vorn zu erfinden.

Grüße
Stilgar