Ich konnte eine Seite von Safari Books Online finden, die a template bietet, aber noch nie POD-Kommentare geschrieben habe, bin ich mir nicht sicher, wie gut es ist oder etwas fehlt, das als Konvention gelten könnte.Gibt es Konventionen für das Schreiben von POD-Kommentaren für Perl?
Welche Konventionen müssen beim Schreiben von POD-Kommentaren für Perl-Skripts beachtet werden? Gibt es etwas wie Sun's Javadoc Conventions, aber für POD Kommentare?
Es ist nicht aufwendig, aber ich mag Juerds perlpodtut Einführung viel.
Der Autor erwähnt, was er gemeinsame Abschnitte und was sie einschließen würde.
Es gibt eine Reihe von Empfehlungen in Perl Best Practices. Das gesamte Kapitel 7 behandelt die Dokumentation, die Verwendung von POD und die besten Ansätze für die Dokumentation von Modulen, großen Projekten usw. Es spricht auch über CPAN-Konventionen. Das ist wahrscheinlich die beste Wette.
Perl::Critic bietet die folgenden Richtlinien:
A list of required sections wird von der letzten oben genannten Richtlinie zur Verfügung gestellt.
Module::Starter::PBP generiert den Code für Sie.
Die "Tipps zum Schreiben Pod" sind nicht über Inhalte. Ich sollte meine Frage wahrscheinlich bearbeiten, um klarer zu sein, aber ich bin speziell auf der Suche nach Inhalten und Design (Schnitt, Überschrift, Einrückung ...) Konventionen. Ich schaue mir die RequirePodSections an, um die Vorlage, die ich angeschaut habe, zu modifizieren, um zu versuchen, sie zu verbessern. –
Ja, +1 für die standardmäßig erforderlichen Abschnitte des RequirePodSections-Dokuments. Ich verwende das, um die ursprüngliche Vorlage zu ändern, mit der ich verlinkt bin. Ich denke, ich habe etwas, das anständig ist, was besser ist als das, womit ich angefangen habe. –
Sie können den Pod für die Perl-Module unter CPAN Search ansehen und schnell die Dinge notieren, die jeder tut. Die verschiedenen Modul-Startwerkzeuge machen für Sie ein Muster.
Das ist ungefähr so nah wie Sie Richtlinien erreichen werden.
Wissen Sie, ob etwas davon frei online verfügbar ist? Ich mag den Buchvorschlag (besonders, weil er sehr vollständig und ausführlich aussieht), aber etwas, das frei verfügbar ist, um mich zu beginnen, wäre das Beste. –
@Thomas Owens: Ich glaube nicht, dass irgendein Buchinhalt frei online verfügbar ist. Sinans Verbindung zu Perl :: Critic ist gut. Eine weitere Option ist die Dokumentation einiger Kern-CPAN-Module. Obwohl die Ansätze etwas variieren können, gibt es Standardabschnitte usw., die als Richtlinien hilfreich sind. –