asmDoc

Was ist asmDoc

asmDoc analysiert und interpretiert Assembler Code und erzeugt daraus eine HTML Dokumentation. Es ist in etwa vergleichbar mit JavaDoc, nur wurde die Syntax an die Bedürfnisse einer Assembler Sprache angepasst.

asmDoc ist in der vorliegenden Version vorwiegend für TASM (Turbo Assembler von Borland) entwickelt worden. Vorschläge zur Erweiterung nehmen wir gerne entgegen.

Durch den Aufruf von asmDoc mit der Haupt Assembler Datei werden alle Include Dateien berücksichtigt. Prozeduren und Strukturen werden automatisch herausgefiltert. Zur Dokumentation können sogenannte asmDoc Kommentare zu den jeweiligen Prozeduren geschrieben werden.

asmDoc liegt momentan in zwei vom allgemeinen Funktionsumfang identischen Versionen vor. Funktionen die sehr Speicherintensiv sind, werden in der DOS Version allerdings bis auf weiteres nicht implementiert werden.

Beide Versionen wurden komplett in Assembler geschrieben.

• asmDoc.com
  Dos Version
  Arbeitet nur in den unteren 640 KB DOS Speicher.
  Benötigt 386 CPU (RealMode).
  DOS System mit langen Dateinamen von Vorteil
  
  
• asmDocW.exe
  Win32 Version
  Benötigt Windows im 32Bit Modus.
  Features die in asmDoc fehlen:
  - alphabetische Sortierung der Index Dateien
  - @see Verlinkung
  - Links werden HTML Konform gespeichert ("\" als "/").
  
  

• Ein Projekt wird ab einer bestimmte Grösse unübersichtlich und die Wartbarkeit und Erweiterbarkeit leidet sichtlich.
• Ein Projekt das nach einer längeren Pause erweitert werden soll, erfordert ohne Dokumentation viel Einarbeitungszeit und wird Fehleranfällig, da nicht (mehr) klar ist, wie einzellne Abschnitte des Programms arbeiten.
• Ohne Dokumentation ist das Arbeiten mehrerer Personen an einem Projekt sehr schwer zu synchronisieren. Die Arbeit geht oft nur langsam voran, da immer wieder Rücksprachen notwendig sind, wie einzellne Elemente des Programms arbeiten und zu verwenden sind.
• Projekte werden von Personen weiter entwickelt die ursprünglich nicht am Projekt beteiligt waren.
• Eine Person steht für Fragen bezüglich des bisherigen Programmierung nichtmehr zur verfügung.
• Das schreiben von APIs (Application Programmer Interfaces).

• Inkonsistenz:
  Sind Dokumentation und Programmierung getrennte Aufgabenbereiche, so ensteht das Problem, dass der Programmcode im Laufe seiner Entwicklung etwas anderes tut als die Dokumentation erwarten lässt.
• Es fordert den Programmierer dazu auf, die Vorbedinungen, Rückgaben und Fehlerquellen gründlich zu überdenken.
• Es spart Zeit.