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";
}