Wenn die Dokumentation direkt den Quellen entnommen wird, werden häufig speziell markierte Bereiche oder bestimmte Kommentare betrachtet. Bei Perl gibt es in einer Quelle im Grunde genommen zwei Sprachen (Perl und POD, das für plain old documentation steht), die einfach lexikalisch voneinander zu trennen sind. Somit kann der Perl-Interpreter einfach die POD-Texte überlesen, während die POD-Konvertierer den Perl-Programmtext ignorieren kann. POD ist sehr einfach und kann somit in eine Vielzahl von Formaten ohne größeren Aufwand konvertiert werden: einfacher ASCII-Text, UNIX-Manualseiten, LATEX und HTML. So sieht z.B. der Anfang von File::Basename aus:
package File::Basename;
=head1 NAME
fileparse - split a pathname into pieces
basename - extract just the filename from a path
dirname - extract just the directory from a path
=head1 SYNOPSIS
use File::Basename;
($name,$path,$suffix) = fileparse($fullname,@suffixlist)
fileparse_set_fstype($os_string);
$basename = basename($fullname,@suffixlist);
$dirname = dirname($fullname);
($name,$path,$suffix) = fileparse("lib/File/Basename.pm","\.pm");
fileparse_set_fstype("VMS");
$basename = basename("lib/File/Basename.pm",".pm");
$dirname = dirname("lib/File/Basename.pm");
=head1 DESCRIPTION
These routines allow you to parse file specifications into useful
pieces using the syntax of different operating systems.
[...]
=over
=item C<basename>
The basename() routine returns the first element of the list produced
by calling fileparse() with the same arguments, except that it always
quotes metacharacters in the given suffixes. It is provided for
programmer compatibility with the UNIX shell command basename(1).
=item C<dirname>
The dirname() routine returns the directory portion of the input file
specification. When using VMS or MacOS syntax, this is identical to the
second element of the list produced by calling fileparse() with the same
input file specification. (Under VMS, if there is no directory information
in the input file specification, then the current default device and
directory are returned.) When using UNIX or MSDOS syntax, the return
value conforms to the behavior of the UNIX shell command dirname(1). This
is usually the same as the behavior of fileparse(), but differs in some
cases. For example, for the input file specification F<lib/>, fileparse()
considers the directory name to be F<lib/>, while dirname() considers the
directory name to be F<.>).
=back
=cut
require 5.002;
require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(fileparse fileparse_set_fstype basename dirname);
#use strict;
#use vars qw($VERSION $Fileparse_fstype $Fileparse_igncase);
$VERSION = "2.5";
[...]
Ein Gleichheitszeichen zu Beginn der Zeile eröffnet eine POD-Direktive und startet ggf. den POD-Bereich, der durch ¯cut beendet wird. Somit wird der Teil danach (ab require 5.002) wieder vom Perl-Interpreter berücksichtigt.
Bei Eiffel ist eine solche strikte Trennung nicht üblich. Stattdessen werden die Quellen der Schnittstellen direkt in einer leicht manipulierten Form präsentiert. Mitgeliefert werden bei Eiffel zwei Werkzeuge namens short und flat. Beide erhalten als Argument ein Modul, wovon short nur die Schnittstelle (also die nach außen sichtbaren Teile) ausgibt, während flat die Ausgabe um alle exportierten Teile der übergeordneten Klassen erweitert. Somit ist bei flat mit einem Blick sichtbar, welche Operationen alle möglich sind, ohne daß eine größere Menge von Referenz-Seiten nacheinander studiert werden muß. Dies ist insbesondere wertvoll, weil bei Eiffel im Zuge von Erweiterungen Operationen umgetauft werden können und somit die Dokumentation einer übergeordneten Schnittstelle garnicht mehr direkt zutrifft.
Bei der Ulmer Oberon-Bibliothek gab es von Beginn an eine parallele Dokumentation zu jedem Modul in Form von UNIX-Manualseiten (zu formatieren mit dem ms-Paket unter troff). Sobald das Web und HTML zur Verfügung standen, wurden Perl-Skripte entwickelt, die sowohl die Manualseiten als auch die Quellen in HTML konvertieren konnten (siehe Abbildung 4.5). Damit steht nicht nur die Dokumentation im Web zur Verfügung, sondern auch die Quellen, wobei dort jede Verwendung importierter Prozeduren oder anderer Deklarationen mit einem Verweis auf die entsprechende Dokumentation versehen ist. Umgekehrt ist es auch möglich, zielgerichtet von der Referenz-Dokumentation an die entsprechende Stelle der zugehörigen Quelle zu wechseln. Dies wurde entscheidend durch die Pflicht zur Benutzung qualifizierter Namen in Oberon erleichtert und damit wird der Einsatz aufwendiger CASE-Tools zur Analyse des Programmtexts erspart, wie er teilweise bei C++ unumgänglich ist.
