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

Jede Anregung, wie kann ich das Dokument meinem Perl-code? Was habt Ihr benutzt und welche Werkzeuge gibt es, um mir zu helfen?

Welches Modul verwenden Sie zum konvertieren von pod-html?

InformationsquelleAutor der Frage | 

  1. 47

    Blick in fast alle Perl-module und du wirst sehen, die Plain Old Documentation (POD) - format. Auf CPAN-Suchewenn man ein Modul haben Sie die option zum anzeigen der raw-Quelle, so dass ist eine Möglichkeit, Sie können Aussehen auf die roh-pod, aber Sie können auch verwenden, perldoc von der Befehlszeile aus. Die -m Schalter zeigt Ihnen die Datei

    perldoc -m Foo::Bar

    Oder, wenn Sie wollen, um die Datei zu suchen, so dass Sie sehen können in Ihrem Lieblings-editor, verwenden Sie das -l Schalter, um es zu finden:

    perldoc -l Foo::Bar

    Sobald Sie beginnen, dokumentieren Sie Ihr Programm, setzen Sie den Pod in die Datei direkt mit dem code, entweder verwoben mit der code so in der Dokumentation ist neben der entsprechenden Teile, oder am Anfang, in der Mitte oder am Ende als ein großer Brocken.

    Pod ist leicht übersetzt in mehrere andere Formate, wie z.B. LaTeX -, Postscript -, HTML, und so weiter, mit übersetzern, die mit Perl (pod2latex, pod2ps, pod2html). Ich habe sogar eine pod-übersetzer, geht in InDesign. Schreiben Sie Ihre eigene Kabine übersetzer ist einfach mit Pod::Simpleso dass, wenn Sie nicht finden, einen übersetzer, um Ihre Lieblings-endgültige form, nur machen Sie es selbst.

    Gibt es auch mehrere tools, die Sie hinzufügen können, um Ihre test-suite zur überprüfung Ihres Pod. Die Test::Pod Modul-Prüfungen bei einem format-Fehler, die Test::Pod::Coverage - Modul überprüft die Sie dokumentiert haben, jeder Unterroutine, und so weiter. Sie könnten auch interessiert sein in meinem Perl-Dokumentation Dokumentation.

    InformationsquelleAutor der Antwort brian d foy

  2. 25

    Empfehle ich auf jeden Fall POD.

    POD kann auch verwendet werden in-line mit dem code, aber ich lieber am unteren Rand des Programms nach __END__ (als empfohlen von Damian Conway in Perl Best Practices).

    Blick auf POD::Server & POD::Webserverwelches ein web-front-end, um alle Ihre PODs.

    InformationsquelleAutor der Antwort draegtun

  3. 20

    Perl-pod.

    Dies ist, wie Mozilla-Dokumente Ihre Perl.

    InformationsquelleAutor der Antwort GavinCattell

  4. 10

    Nicht allzu flip, aber der beste Weg, um Dokument Perl-code ist die gleiche Weise, als würden Sie die Dokument-code in einer anderen Sprache.

    Für spezielle tools, ich verwende einen mix aus standard-inline-Kommentare, pod für größere Abschnitte der Dokumentation, wo ein ähnliches format wie Mann geeignet ist, und TeX als letztes fallback für Dokumente, die brauchen, um mehr Freiform. (Und, im Sinne von "das gleiche wie jede andere Sprache", ja, ich verwende pod für die Dokumentation von nicht-Perl-code als auch.)

    InformationsquelleAutor der Antwort Dave Sherohman

  5. 6

    Welches Modul verwenden Sie zum konvertieren von pod
    html?

    Check-out Pod::ProjectDocs - Sie erhalten einen einfachen Befehlszeilen-Dienstprogramm, das konvertieren der POD in einem Perl-Projekt in einen Satz von HTML-Seiten, die genauso Aussehen wie das, was Sie sehen auf search.cpan.org.

    InformationsquelleAutor der Antwort JDrago

  6. 3

    Vielleicht wollen Sie auch heraus zu überprüfen Perl Best Practices von Damian Conway. Ich habe einige der Tipps, um aufzuräumen ein kleines Perl-code-Basis, die ich geerbt.

    InformationsquelleAutor der Antwort

  7. 3

    Niemand erwähnt Smart::Kommentare? Es ist nicht immer, was Sie wollen, aber gut, wenn du mehr power brauchst, um Kommentare.

    InformationsquelleAutor der Antwort

  8. 2

    separaten user-docs und Programmierer docs. vielleicht steckte user docs (tuts, faq, Referenz) im es-Verzeichnis (/doc) und Programmierer in der gleichen wie der code. leider erwarteten von conventtion, um übersicht in das Modul selbst. diese können Sie wie schon layed out-tun Sie es-POD nach ENDE. Mähne Codierung docs kannst du in die Kommentare. zusätzliche Dinge wie coding style oder wie Sie dazu beitragen legen Sie in getrennten .pod-Dateien in der code-Basis (root-dir?)

    InformationsquelleAutor der Antwort

Schreibe einen Kommentar