OOP: Dokumentation von Interfaces im POD

28/03/2009 - 12:35 von Achim Grolms | Report spam
Gegeben seien zwei Packages A und B die
"dasselbe Interface implementieren".
A und B stellen also einen Satz gleichnamiger
Methoden mit gleicher Bedeutung für den Aufrufer bereit.

Die Doku der Interface-Methoden für den Nutzer der Packages
(Namen, Aufrufkonvention,... ) gehört
da nun meiner Meinung nach nicht in das POD von A oder
in das POD von B sondern "zum Inteface", denn ansonsten
würd ja die Doku in das POD von A und B gecopypasted und
müßte an zwei Stellen gepflegt werden.

In bspw. Java würde man da ein 'interface' einführen
und dieses entsprechend dokumentieren, die Doku
würde gelten für alle Klassen die das 'interface'
implementieren.

Für mein Problem hatte ich die Idee "das Interface"
separat in einer .pod - Datei zu beschreiben und
in A und B jeweils nur auf das Interface-POD zu verweisen.
Kommt Package C hinzu welches dasselbe Interface implementiert
braucht die Doku von C nur den Verweis auf das Interface-POD.

Welche Probleme seht ihr bei der Vorgehensweise,
wie geht ihr diese Fragestellung an,
Wißt ihr im Netz ein Beispiel wo man sich
so eine Strukturierung abgucken könnte?
 

Lesen sie die antworten

#1 Frank Seitz
30/03/2009 - 18:27 | Warnen spam
Achim Grolms wrote:
Gegeben seien zwei Packages A und B die
"dasselbe Interface implementieren".
A und B stellen also einen Satz gleichnamiger
Methoden mit gleicher Bedeutung für den Aufrufer bereit.

Die Doku der Interface-Methoden für den Nutzer der Packages
(Namen, Aufrufkonvention,... ) gehört
da nun meiner Meinung nach nicht in das POD von A oder
in das POD von B sondern "zum Inteface", denn ansonsten
würd ja die Doku in das POD von A und B gecopypasted und
müßte an zwei Stellen gepflegt werden.

In bspw. Java würde man da ein 'interface' einführen
und dieses entsprechend dokumentieren, die Doku
würde gelten für alle Klassen die das 'interface'
implementieren.

Für mein Problem hatte ich die Idee "das Interface"
separat in einer .pod - Datei zu beschreiben und
in A und B jeweils nur auf das Interface-POD zu verweisen.
Kommt Package C hinzu welches dasselbe Interface implementiert
braucht die Doku von C nur den Verweis auf das Interface-POD.

Welche Probleme seht ihr bei der Vorgehensweise,
wie geht ihr diese Fragestellung an,
Wißt ihr im Netz ein Beispiel wo man sich
so eine Strukturierung abgucken könnte?



Ich mache es so wie du, nur sind Interfaces bei mir
abstrakte Basisklassen. Diese haben ggf. auch ein paar
implementierte Methoden. Es sind also ganz normale pm-Dateien,
inklusive POD. Perl und POD unterstützen solche Abhàngigkeiten
in keinster Weise, von daher bist du beim Erstellen der Doku
auf dich allein gestellt. Es gibt aber auch Werkzeuge dafür,
z.B. http://search.cpan.org/~markov/OODoc-1.05

Grüße
Frank Seitz
Dipl.-Inform. Frank Seitz; http://www.fseitz.de/
Anwendungen für Ihr Internet und Intranet
Tel: 04103/180301; Fax: -02; Industriestr. 31, 22880 Wedel

Ähnliche fragen