Dokumentation eines Moduls

Tokens | Dokumentation eines Moduls | Plain Old Documentation - POD

Dokumentation eines Moduls

Bevor wir zur eigentlichen Dokumentation eines Perlmoduls kommen, möchte hier noch ein Hilfsmittel erklären, die sogenannten Tokens.

Tokens

Tokens dienen dazu in einem Perlskript Abschnitte zu markieren. Sie sind daher sehr auffällig von ihrer Gestalt: __IRGENDWASGROSSGESCHRIEBENES__.

Folgende Tokens stehen völlig allein in einer Zeile.

Token	Beschreibung
__END__	Markiert im File das Ende des Programms. Danach darf beliebiger Text stehen. Dieser wird vom Perlinterpreter nicht berücksichtigt.
__DATA__	Markiert im File das Ende des Programms. Danach darf beliebiger Text stehen. Dieser wird vom Perlinterpreter nicht berücksichtigt, kann aber mittels des Dateihandles DATA gelesen werden.

Diese Tokens stehen im Code selbst:

Token	Beschreibung
__LINE__	Die aktuelle Zeilennummer des Programms.
__PACKAGE__	Der Name des aktuellen Packages.
__FILE__	Der Dateiname des aktuellen Perlprogramms.

print "TOKENS\n";
print "\n";
print "Das ist die ".__LINE__.
". Zeile des Perlprogramms '".__FILE__.
"' im Package '".__PACKAGE__."'.\n";

__END__

Testprogramm token.pl

TOKENS

Das ist die 3. Zeile des Perlprogramms 'token.pl' im Package 'main'.

Dokumentation eines Moduls

Jedem Perlprogramm kann eine Dokumentation hinzugefügt werden. Besonders sinnvoll ist dies bei Modulen. Die Dokumentation wird nicht in ein Extrafile geschrieben, sondern in das File mit dem Code. Es ist sogar möglich Dokumentationen zwischen den Code zu schreiben - was aber nur in seltenen Fällen Sinn macht. Normalerweise ist es so, dass man die ganze Dokumentation nach dem Token __END__ unterbringt - das Programm wird dadurch schneller, weil der Perlinterpreter die Dokumentation nicht bearbeiten muss.

Um die Dokumentation auszugeben gibt es das Programm perldoc - es liest die im angegeben File enthaltene Dokumentation im POD-Format (s. u.) und gibt diese auf die Standardausgabe aus.

Folgende Eingabe auf der Betriebssystemebene ...

perldoc cgi.pm

... liefert:

NAME
    CGI - Simple Common Gateway Interface Class

SYNOPSIS
      # CGI script that creates a fill-out form
      # and echoes back its values.

      use CGI qw/:standard/;
      print header,
            start_html('A Simple Example'),
            h1('A Simple Example'),
            start_form,
            "What's your name? ",textfield('name'),p,
            "What's the combination?", p,

...

Plain Old Documentation - POD

Das oben genannte Programm perldoc wird auf POD-Befehle angewendet. POD-Befehle sind einfache Formatierungsbefehle für Text. Vor jedem POD-Befehl muss eine Leerzeile stehen. Hier eine Auswahl von POD-Befehlen:

=pod	Leitet die POD-Dokumentation ein.
=cut	Beendet die POD-Dokumentation. Und kehrt ggf. zum Perlcode zurück.
=head1 UEBERSCHRIFT	Überschrift 1. Ebene. Sie leitet ebenfalls eine POD-Dokumentation ein.
=head2 UEBERSCHRIFT	Überschrift 2. Ebene
=over N	Rückt in jeder nachfolgenden Zeile N Spalten ein bis die Einrückung aufgehoben wird.
=back	Hebt die Einrückung von =over auf.
=item LISTENEINTRAG	Markierung für einen Listeneintrag.

Text nach einer Leerzeile ist Standardtext. Dieser ist soweit eingerückt, wie es die Umgebeung verlangt - bei =head1 wird weniger eingerückt als bei =head2.

Es gibt noch mehr POD-Befehle. Diese zu nennen, unterlasse ich hier. Vielleicht kommt später eine Ergänzung.

Ein Beispiel für das Modul myMath.pm mit POD:

package myMath;
use Exporter;

@ISA = qw(Exporter);
@EXPORT = qw(&plus &minus &times &over);
@EXPORT_OK = qw($PI);

# data
$PI=3.14159265358979323846;

# functions
sub plus { $_[0]+$_[1]; }
sub minus { $_[0]-$_[1]; }
sub times { $_[0]*$_[1]; }
sub over { $_[0]/$_[1]; }

__END__

=head1 Modul myMath.pm

Dieses Modul enthaelt einige
kleine Mathefunktionen.

=head2 &plus

Eine Funktion, die zwei Zahlen addiert.

=head2 &minus

Eine Funktion, die zwei Zahlen subtrahiert.

...

=cut

1;

Die Dokumentationsausgabe lautet:

C:\>perldoc myMath.pm
Modul myMath.pm
    Dieses Modul enthaelt einige kleine Mathefunktionen.

  &plus

    Eine Funktion, die zwei Zahlen addiert.

  &minus

    Eine Funktion, die zwei Zahlen subtrahiert.

...

Es ist sinnvoll sich eine Dokumentation eines Standardmoduls anzuchauen. Damit lernt man ziemlich schnell wie die "Profis" dokumentieren.

Tokens | Dokumentation eines Moduls | Plain Old Documentation - POD

Perl, Lehrstuhl Mathe II, Uni Bayreuth