Ci sono convenzioni per scrivere commenti POD per il Perl?
Domanda
Sono riuscito a trovare una pagina da Safari Books Online che fornisce un modello , ma avendo commenti POD mai scritte, non sono sicuro di come è bello o se manca qualche cosa che potrebbe essere considerato convenzione per includere.
Quali sono le convenzioni da seguire quando si scrive commenti POD per gli script Perl? C'è qualcosa di simile Convenzioni Javadoc Sun , ma per i commenti POD?
Soluzione
Non è elaborato, ma mi piace perlpodtut introduzione di Juerd un sacco.
L'autore cita ciò che considera le sezioni comuni con il loro includerebbe.
Altri suggerimenti
Ci sono una serie di raccomandazioni in Perl Best Practices . L'intero capitolo 7 comprende la documentazione, con POD, e la migliore si avvicina alla documentazione per i moduli, i grandi progetti ecc parla anche di convenzioni CPAN. Questo è probabilmente la soluzione migliore.
Perl :: Critic fornisce i seguenti criteri:
-
Perl :: Critic :: Politica :: Documentazione :: RequirePackageMatchesPodName
-
Perl :: Critic :: Politica :: Documentazione :: RequirePodAtEnd
-
Perl :: Critic :: Politica :: Documentazione :: RequirePodSections
un elenco di sezioni richieste è fornito dall'ultimo politica di cui sopra.
Module :: Starter :: PBP genererà il codice standard per voi.
È possibile guardare il Pod per i moduli Perl su CPAN Search e rapidamente notare le cose che ognuno fa . I vari moduli di partenza strumenti rendono boilerplate per voi.
Questo è quanto di più vicino si arriva a linee guida.