Testen der Dokumentation

Ein zweiter Bereich, der gerne vernachlässigt wird, ist die Dokumentation. Bei einem Großteil der Programmierer ist dieser Teil vermutlich noch unbeliebter als das Testen von Software. Doch Dokumentation ist wichtig, um Kunden einen Einblick in die Software zu gewähren. Die Dokumentation ist aber auch entscheidend für die Wartbarkeit eines Programms: Ist das Programm nicht dokumentiert, so fällt es häufig schwer, nach drei oder vier Monaten das Programm zu erweitern. ``Wie war das nochmal? Was macht der Codeteil?'' - so oder so ähnliche Sätze hört man dann vor den Bildschirmen.

Um sich selbst und andere Programmierer zu etwas Disziplin zu ``zwingen'', erlaubt es Perl, die Dokumentation zu überprüfen. Es dreht sich hier um die Dokumentation in POD. In den folgenden Sektionen werden zwei Module beschrieben, die für das Testen der Dokumentation verwendet werden können.

Test::Pod

Das erste Modul zum Testen der Dokumentation ist Test::Pod. Es überprüft die POD-Dokumentation auf Korrektheit und vor allem, ob überhaupt etwas da ist! Die Dokumentation wird darauf überprüft, ob sie der Syntax entspricht, die in perldoc perlpod beschrieben ist.

Es wird allerdings nicht überprüft, ob das Programm vollständig dokumentiert ist.

Das Modul exportiert drei Methoden in das Testskript:

• pod_file_ok

  Diese Funktion wird verwendet, wenn die POD-Dokumentation einer einzelnen Datei überprüft werden soll. Dementsprechend kann man der Funktion einen Dateinamen übergeben. Wie von den meisten Testfunktionen kann auch pod_file_ok ein Name für den Test übergeben werden.

  Der Aufruf dieser Funktion sieht dann beispielsweise so aus: pod_file_ok('My/Module.pm','test of My::Module')

  Hier ein Beispielskript:

   1 #!/usr/bin/perl
   2
   3 use Test::Pod tests => 1;
   4 pod_file_ok($0);
   5
   6 =pod
   7
   8 =head1 Test
   9
   10 this is a test for Test::Pod
   11 
   12 =cut
  

  Die Ausgabe dieses Programms sieht dann wie folgt aus:

   C:\community>perl test_pod_1.pl
   1..1
   ok 1 - POD test for test_pod_1.pl

• all_pod_files_ok

  Soll die Dokumentation von mehreren Dateien überprüft werden, so kann die Funktion all_pod_files_ok verwendet werden. Der Aufruf ist gleich dem Aufruf von pod_file_ok.

• all_pod_files

Test::Pod::Coverage

-- ReneeBaecker - 15 Apr 2009