NaturalDocs Dokuementation des zBot

Sehr schön an NaturalDocs ist, dass die Dokumentation sehr nahe an natürlichsprachlichem Plaintext ist und sich die Beschreibungen von Klassen oder Methoden auch sehr gut aus den Quellen lesen lässt ohne dass man die Syntax von NaturalDocs kennen muss. Auch einfache Textdateien wie eine Readme oder ähnliches können damit erstellt werden. So kann man (zumindest bei kleineren Projekten) sogar sämtliche Dokumente wie Anforderungen, UML-Diagramme, … mit NaturalDocs erstellen, wodurch man alle Informationen an einem Ort gebündelt und in einem einheitlichen Format vorliegen hat.

Das Perl-Tool versteht auch JavaDoc, so dass eine Umstellung erleichtert wird.

Gestartet wird NaturalDocs mittels:
NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]
wobei ich mir ein kleines Script zum erstellen/aktualisieren der Dokumentation erstellt habe, welches ein Changelog beinhaltet, welches aus einem svn log automatisch generiert wird. Das Script habe ich unten angehängt.

Ein Beispiel in perl:

# SUB: multiplicate
# 
# multiplicates two numbers
# 
# PARAMETERS:
# $a - first parameter
# $b - second parameter
#
# RETURNS:
# the product of $a and $b
sub multiplicate {
    $a=shift;
    $b=shift;
    return $a*$b;
}

So sieht die Dokumentation einer einfachen Funktion aus. Bei Sprachen die full language support besitzen (bisher perl, ActionScript und C#) kann auch eine JavDoc-artige Dokumentation genutzt werden:

##
# multiplicates two numbers
# 
# PARAMETERS:
# $a - first parameter
# $b - second parameter
#
# RETURNS:
# the product of $a and $bsub multiplicate {
    $a=shift;
    $b=shift;
    return $a*$b;
}

Beide Beispiele haben das selbe Ergebnis:

NaturalDocs Beispiel

Listen können erstellt werden, indem eine Zeile mit “-” angefangen wird. Definitionen haben ein “-” zwischen Bezeichner und Definition. Es können auch Grafiken, Beispielquelltexte und ASCII-Diagramme eingefügt werden.

Leider kann NaturalDocs von Haus aus nicht mit Listen in Listen umgehen, doch dafür gibt es einen Patch: Nested Bullets, womit man durch + oder * eine Liste in der Liste einleitet.
Installiert wird es, indem die Datei Native.pm.diff nach $NATURALDOCS_PATH/Modules/NaturalDocs/Parser Kopiert wird und dann der Befehl

patch Native.pm Native.pm.diff

aufgerufen wird.

Einen neuen Absatz erzwingt man durch eine Leerzeile. Eine Überschrift kann mittels # Überschrift: eingefügt werden, wobei die Zeile darüber leer sein muss.
Es kann auch auf Webseiten, Emailadressen und andere Stellen der Dokumentation verlinkt werden.
Natürlich kann auch unterstrichen und fett geschrieben werden. Die Zusammenfassung wird automatisch erstellt.

Cool ist auch die Möglichkeit der Abkürzung, womit man mehrere Defines, Funktionen oder Variablen zusammenfassend dokumentieren kann. So kann man statt dem folgenden Code

# VARIABLE: $configFile
# Filename of configuration file
$configFile = "config.txt";
 
# VARIABLE: $inputFile
# Filename of input file
$inputFile = "input.txt";
 
# VARIABLE: $outputFile
# Filename of output file
$outputFile = "out.txt";

die Variablen für die Dateinamen zusammen fassen:

# VARIABLES: Filenames
# $configFile - Filename of configuration file
# $inputFile - Filename of input file
# $outputFile - Filename of output file
$configFile = "config.txt";
$inputFile = "input.txt";
$outputFile = "out.txt";

Dabei können mehrere solcher Blöcke für verschiedene Belange angelegt werden (z.B. Dateinamen, Logindaten für Datenbank, …). Das Ergebnis sieht dann so aus:

NaturalDocs - Variablen zusammenfassend dokumentiert

Auch mein Jabber Bot zBot ist mit NaturalDocs dokumentiert. Als Beispiel kann man sich dessen Dokumentation ansehen.

Für Neulinge gibt es ein schönes Walktrough, wo die ersten Schritte mit NaturalDocs erklärt werden.

Hier noch das Script, welches eine von NaturalDocs lesbare Changelist im Ordner documents und dann die Dokumentation selbst erstellt:

#!/usr/bin/perl
 
# Script: makedocs.pl
#
# This script generates the documentation.
#
# Requirements:
#
# - NaturalDocs path must be in ENV variable $NATURALDOCS_PATH
# - Projectdirectory naturaldocs has to be in the same directory as this script
# - There must be a (empty) directory documentation in the same directory as this script
#
# Usage:
#
# Just start this script when something has changed or use the script <make.pl>
#
# > tools/makedocs.pl [OPTIONS]
#
# Options:
#
#  -o - start makedocs.pl in offline modus
#
# In offlinemode the changelog is not generated
#
#
# SVN:
#
# Commit only the textfiles of the projectdirectory (Not the directory "Data") from NaturalDocs.
#
# The documentation directory should be an empty dir in SVN.
#
# So everybody can create the documentation by himself just by executing this script.
 
use strict;
use warnings;
use vars qw (%ENV);
 
# Sub: generatechangelog
#
# Generates documents/changelog.txt from svn log -v
#
sub generatechangelog {
    print "Generating changelog...n";
    $ENV{LANG} = "C";
    my $log = `svn log -v`; 
 
    $log =~ s/(-){2,}//g;
    $log =~ s/(r[0-9]{1,4})/$1:nn$1/g;
    $log =~ s/n/nn/g;
    $log =~ s/Pfade:/Pfade/g;
    $log =~ s/paths:/paths/g;
    $log =~ s/([A-Z] /)/- $1/g;
 
    open(DATEI, ">documents/changelog.txt");
    print DATEI "Title: Changelognn$log";
    close DATEI;
    print "Done.n";
}
 
######### PROGRAM START ############
 
if (defined $ENV{NATURALDOCS_PATH} && $ENV{NATURALDOCS_PATH} ne "") {
    generatechangelog() if (not(defined @ARGV && $ARGV[0] eq "-o"));
# Generate documentation of current directory in HTML and save to directory documentation. Projectdirectory is naturaldocs.
# Ignore directory tests
    system
"$ENV{NATURALDOCS_PATH}/NaturalDocs -i . -o HTML ./documentation -p ./naturaldocs -xi ./tests";
} else {
    print "Environment variable $NATURALDOCS_PATH not defined!n";
}

Das StayOnline Hauptfenster

Bisher gab es das Bottertool, welches diesen Zweck erfüllte. Jedoch nur für Windows.

StayOnline ist unter der GPL veröffentlicht und unterstützt wie das Bottertool einige Replacer (wenn auch nicht alle) und hat eine Funktion “bei Logout schließen”, die das Programm schließt, wenn keine Verbindung mehr besteht (allerdings erst, wenn die Zeit abgelaufen ist, da erst beim Senden erkannt werden kann, ob noch eine Verbindung besteht)
Der Text kann jederzeit geändert werden, also auch während der Countdown läuft.

Vorraussetzungen:
Java 1.5 oder höher kann man bei http://java.sun.com kostenlos herunterladen (das jre). Java sollte jedoch auf den meisten Windows Systemen (und auch den meisten anderen Betriebssystemen) bereits installiert sein.

Starten des Programms:
Unter Windows sollte ein Doppelklick genügen.
Auf anderen Systemen (und wenns unter Windows nicht mit Doppelklick funktioniert) geht man in die Konsole (unter Windows:  Start -> Ausführen und dann cmd eingeben)
und gibt dort (im richtigen Verzeichnis, welches man mit cd wechseln kann) “java -jar stayonlinev013.jar” (ohne die “) ein.

Einstellungen

• Username: ist wohl klar, der Username des Webkicks Users
• Link zur Message Box: hier kommt der Link zur Message Box rein. Mit rechter Maustaste auf die Message Box im Webkicks Chat klicken und “Linkadresse Kopieren” (oder entsprechendes je nach Browser) auswählen. Dann in den Einstellungen von StayOnline mit Strg+V ins entsprechende Fenster einfügen.
• Zeit: die Zeit zwischen zwei Nachrichten in Sekunden (900 sind 15 Min)

Einstellungen von StayOnline

Die Einstellungen werden beim Starten in eine Datei data.txt ins gleiche Verzeichnis geschrieben, in der sich auch die .jar-Datei befindet. Beim erneuten Laden des Programms wird diese geladen und ausgewertet.

Hier die Replacer, wenn man diese sendet werden Sie automatisch ersetzt:

• $u wird ersetzt durch den Usernamen
• $cnt wird durch die Anzahl der (vom Programm) gesendeten Nachrichten ersetzt
• $ver wird durch die Version des Programmes ersetzt

Quelltext selber compilieren:
Hierfür benötigt man das Java JDK. Man entpackt die stayonline_src.zip in einen neuen Ordner und führt in diesem Ordner folgende Befehle aus:

javac *.java

jar cvfm stayonline.jar MANIFEST.MF *.class

Die dabei erzeugte Datei stayonline.jar kann man nun verschieben wie man mag und wie oben beschrieben ausführen. (unter Linux sind afaik keine Rechte zum ausführen notwendig)

Ausführliche Anleitung

Falls das jemandem zu schnell ging oder noch nicht ganz klar ist, wie man das Programm zum laufen bekommt, hier noch eine Schritt für Schritt Anleitung:

1. Verzeichnis erstellen: C:ProgrammeStayOnline (kann auch wo anders sein)
2. Datei Herunterladen und in das Verzeichnis kopieren: stayonlinev013.jar
3. Doppelklick auf die Datei, dann auf Einstellungen klicken.
4. Im Chat mit der rechten Maustaste auf die “Message Box” klicken und “Linkadresse kopieren” (oder Sinngemäßes je nach Browser) auswählen.
5. Bei “Link zur Message Box” einfügen (Strg gedrückt halten und einmal v drücken)
6. Bei “Text” den gewünschten Text eingeben, der nach ablauf des Timers vom User im Chat gesagt werden soll
7. Gewünschte Zeit eingeben, wie lange gewartet werden soll bis der Text erneut ausgegeben wird (in Sekunden)
8. Häckchen bei “bei Logout schließen” machen
9. Auf OK klicken und dann im Hauptfenster auf Start. Fertig

(Falls sich das Programm bei einem Doppelklick nicht öffnet:
Start->Ausführen dort cmd eingeben. im MSDOS-Fenster java -jar C:ProgrammeStayOnlinestayonlinev013.jar eingeben und Enter drücken.)

Man kann nun noch eine Verknüpfung erstellen, um nicht immer in das Verzeichnis gehen zu müssen um das Programm zu starten:

1. Rechte Maustaste auf Desktop -> Neu -> Verknüpfung
2. C:Programme/Java/jre/bin/java auswählen.
3. Auf OK, bis Verknüpfung fertig ist.
4. Rechte Maustaste auf die Verknüpfung -> Einstellungen
5. Den auszuführenden Befehl ändern auf: C:Programme/Java/jre/bin/java – jar C:ProgrammeStayOnlinestayonlinev013.jar
6. Verzeichnis in dem Das Programm ausgeführt werden soll: C:ProgrammeStayOnline

Fertig

Die Dateien

• stayonlinev013.jar – Die Ausführbare Date, das eigentlich Programm
• stayonlinev013_src.zip – Die Quelltexte inclusive der Manifest-Datei
• stayonlinev013_doc.zip – Die Dokumentation