Was ist der beste Weg, Perl-Code zu dokumentieren?

Question

Irgendwelche Vorschläge, wie ich meinen Perl-Code dokumentieren kann? Was verwendest du und welche Hilfsmittel stehen mir zur Verfügung?

Welches Modul verwenden Sie zum Konvertieren von Pod in HTML?

Answer 1

Schauen Sie sich fast jedes Perl-Modul an und Sie werden das Format Plain Old Documentation (POD) sehen. Unter CPAN Search haben Sie beim Betrachten eines Moduls die Möglichkeit, die rohe Quelle anzuzeigen, so dass Sie den Roh-Pod betrachten können. Sie können aber auch perldoc über die Befehlszeile verwenden. Der -m Schalter zeigt Ihnen die Datei

perldoc -m Foo::Bar 

Oder, wenn Sie die Datei finden mögen, so dass Sie es in Ihrem bevorzugten Editor aussehen können, verwenden Sie die -l Schalter zu finden:

perldoc -l Foo::Bar 

Einmal Sie beginnen, Ihr Programm zu dokumentieren, Sie setzen den Pod in die Datei mit dem Code ein, der entweder mit dem Code verwoben ist, so dass die Dokumentation neben den relevanten Teilen steht, oder zu Beginn, Mitte oder Ende als ein großer Brocken.

Pod kann leicht in mehrere andere Formate übersetzt werden, wie LaTeX, Postscript, HTML und so weiter mit den Perl-eigenen Übersetzern (pod2latex, pod2ps, pod2html). Ich habe sogar einen Pod-Übersetzer, der an InDesign geht. Mit Pod::Simple ist es ganz einfach, einen eigenen Pod-Übersetzer zu schreiben. Wenn Sie also keinen Übersetzer für Ihre Lieblingsform finden, machen Sie es einfach selbst.

Es gibt auch verschiedene Tools, die Sie zu Ihrer Testsuite hinzufügen können, um Ihren Pod zu überprüfen. Das Modul Test::Pod prüft auf Formatfehler, das Modul Test::Pod::Coverage prüft, ob Sie die einzelnen Unterroutinen dokumentiert haben und so weiter. Sie könnten auch an meinem Perl documentation documentation interessiert sein.

Answer 2

Perl pod.

So dokumentiert Mozilla ihre Perl.

Answer 3

Nicht übermäßig Flip sein, aber der beste Weg, Perl-Code zu dokumentieren, ist die gleiche Art und Weise, wie Sie Code in einer anderen Sprache dokumentieren würden.

Wie für spezifische Werkzeuge, verwende ich eine Mischung aus Standard-Inline-Kommentaren, Schote für größere Brocken von Dokumentation, wo ein ähnliches Format wie Mann geeignet ist, und TeX als letzter Rückfall für Dokumente, die mehr Freiform sein müssen. (Und im Geiste von "selbe wie jede andere Sprache", ja, verwende ich auch pod für die Dokumentation von Nicht-Perl-Code.)

Answer 4

Ich empfehle auf jeden Fall POD.

POD kann auch inline mit Code verwendet werden, aber ich ziehe es vor, das Programm nach __END__ (wie von Damian Conway in Perl Best Practices empfohlen) zu setzen.

Betrachten Sie POD::Server & POD::Webserver, die ein Web-Front-End für alle Ihre PODs bietet.

Answer 5

Welches Modul verwenden Sie, um Pod in HTML umzuwandeln?

Check out Pod::ProjectDocs - Sie ein einfaches Befehlszeilenprogramm erhalten, das all POD in Perl-Projekt in eine Reihe von HTML-Seiten konvertiert, die nur aussehen wie das, was Sie auf search.cpan.org sehen.

Answer 6

Sie können auch überprüfen, Perl Best Practices von Damian Conway. Ich habe einige der Tipps verwendet, um eine kleine Perl-Code-Basis zu bereinigen, die ich geerbt habe.

Answer 7

Niemand erwähnt Smart::Comments? Es ist nicht immer das, was Sie wollen, aber es ist gut, wenn Sie mehr Kommentare brauchen.

Answer 8

separate Benutzerdokumente und Codierer. Vielleicht legen Sie die Benutzerdokumente (Tuts, FAQ, Referenz) in das Verzeichnis (/ doc) und die Codierer in den gleichen Code. Leider wird es von der Konventation erwartet, um im Modul selbst einen Überblick zu haben. dies können Sie wie bereits ausgeführt tun es POD nach END. Mane Coding Docs können Sie Kommentare einfügen. zusätzliche Dinge wie Codierung Stil oder wie Sie beitragen, in separate .pod-Dateien in der Code-Basis (Root-Verzeichnis?)