J'ai pu trouver une page de Safari Books Online qui fournit Un modèle , mais N'ayant jamais écrit de commentaires de POD, je ne suis pas sûr à quel point il est bon ou s'il manque tout ce qui pourrait être considéré comme convention à inclure.
Quelles sont les conventions à suivre lorsque vous écrivez des commentaires de POD pour les scripts PERL? Y a-t-il quelque chose comme Conventions Javadoc de Sun , mais pour les commentaires de POD?
4 Réponses :
Il existe un ensemble de recommandations dans Perl meilleures pratiques . L'ensemble du chapitre 7 couvre la documentation, l'utilisation de POD et les meilleures approches de la documentation pour les modules, les grands projets, etc. Il parle également de conventions en CPAN. C'est probablement votre meilleur pari.
Savez-vous si l'un de ceci est librement disponible en ligne? J'aime la suggestion du livre (surtout que cela semble très complet et approfondi), mais quelque chose de librement disponible pour me faire commencer serait mieux.
@Thomas Owens: Je ne pense pas que l'un des contenus de livre est disponible librement en ligne. Le lien de Sinan à Perl :: Le critique est un bon. Une autre option consiste à jeter un coup d'œil à la documentation de certains des modules CORE CPAN. Bien que les approches puisse varier quelque peu, il existe des sections standard, etc. qui sont utiles en tant que directives.
Perl :: Critique fournit les stratégies suivantes:
Perl :: Critique :: Politique :: Documentation :: Podspelling
Perl :: Critique :: Politique :: Documentation :: ConcedePackAmatchSespodName
Perl :: Critique :: Politique :: Documentation :: ContrepodaTend
Perl :: Critique :: Politique :: Documentation :: Exigences
Une liste des sections requises est fourni par la dernière politique ci-dessus.
Module :: Starter :: PBP générera le code de la chaudière pour vous.
Les "astuces pour la rédaction de la pod" ne sont pas sur le contenu. Je devrais probablement modifier ma question pour être plus clair, mais je suis spécifiquement à la recherche de contenu et de conception (sectionnement, en rubrique, indentation ...) Conventions. Je regarde les besoins nécessaires pour modifier le modèle que j'ai examiné pour essayer de l'améliorer.
Oui, +1 Pour les sections requises par défaut, une partie du document de requêtes. J'utilise cela pour modifier le modèle d'origine que j'ai lié à. Je pense avoir quelque chose de décent, ce qui est meilleur que ce que j'ai commencé avec.
Ce n'est pas élaboré, mais j'aime Juterd's Perlpodtut Introduction beaucoup.
L'auteur mentionne ce qu'il considère les sections communes et ce qu'ils comprendraient.
Vous pouvez regarder la POD pour les modules Perl sur CPAN Search et notez rapidement les choses que tout le monde fait . Les différents outils de démarrage du module facilitent la chaudière pour vous.
C'est à peu près aussi proche que vous obtiendrez des directives.