Existem quaisquer convenções para escrever comentários POD para Perl?

Question

Eu era capaz de encontrar uma página a partir do Safari Books Online que fornece um modelo , mas ter comentários POD não escritas, não tenho certeza como é bom ou se está faltando alguma coisa que possa ser considerada convenção para incluir.

Quais são as convenções a seguir ao escrever comentários POD para scripts Perl? Há algo como Convenções Javadoc da Sun , mas para comentários POD?

Answer 1

Não é elaborar, mas eu gosto perlpodtut introdução de Juerd muito.

O autor menciona que ele considera seções comuns eo que eles incluem.

Answer 2

Há um conjunto de recomendações em Perl Best Practices . Todo o capítulo 7 documentação tampas, usando POD, e as melhores abordagens para a documentação para módulos, grandes projetos etc. Ele também fala sobre convenções CPAN. Isso é provavelmente a sua melhor aposta.

Answer 3

Perl :: Critic fornece as seguintes políticas:

• Perl :: Critic :: política :: Documentação :: PodSpelling

• Perl :: Critic :: política :: Documentação :: RequirePackageMatchesPodName

• Perl :: Critic :: política :: Documentação :: RequirePodAtEnd

• Perl :: Critic :: política :: Documentação :: RequirePodSections

A lista de seções necessárias é fornecido pelo último política acima.

Module :: Inicial :: PBP gerará o código clichê para você.

Answer 4

Você pode olhar para o Pod para os módulos Perl em CPAN Pesquisa e rapidamente observar as coisas que todo mundo faz . Os vários módulo ferramentas começando tornar clichê para você.

Isso é aproximadamente tão perto como você vai chegar a diretrizes.