Pude encontrar una página de Safari Books Online que proporciona a template, pero nunca he escrito los comentarios de POD, no estoy seguro de qué tan bueno es o si falta algo que pueda considerarse convencional.¿Hay alguna convención para escribir comentarios de POD para Perl?
¿Cuáles son las convenciones a seguir cuando se escriben comentarios POD para scripts Perl? ¿Hay algo como Sun's Javadoc Conventions, pero para comentarios de POD?
No es elaborado, pero me gusta la introducción de Juerd perlpodtut mucho.
El autor menciona lo que considera secciones comunes y lo que incluirían.
Hay un conjunto de recomendaciones en Perl Best Practices. Todo el Capítulo 7 cubre la documentación, el uso de POD, y los mejores enfoques para la documentación de los módulos, grandes proyectos, etc. También habla sobre las convenciones de CPAN. Esa es probablemente tu mejor opción.
Perl::Critic proporciona las siguientes políticas:
A list of required sections es proporcionada por la última política anterior.
Module::Starter::PBP generará el código repetitivo para usted.
Las "sugerencias para escribir en un pod" no se tratan de contenido. Probablemente debería editar mi pregunta para que sea más clara, pero específicamente estoy buscando contenido y diseño (seccionamiento, encabezado, sangría ...) convenciones. Estoy mirando RequirePodSections para modificar la plantilla que miré para intentar mejorarla. –
Sí, +1 para las secciones predeterminadas requeridas como parte del documento RequirePodSections. Estoy usando eso para modificar la plantilla original a la que me he vinculado. Creo que tengo algo que es decente, que es mejor de lo que comencé. –
Puede consultar el Pod para los módulos Perl en CPAN Search y observar rápidamente las cosas que todos hacen. Las diversas herramientas de inicio del módulo son un modelo para usted.
Eso es lo más cerca que llegarás a las pautas.
¿Sabe si algo de esto está disponible de forma gratuita en línea? Me gusta la sugerencia del libro (sobre todo porque se ve muy completo y profundo), pero sería mejor algo libremente disponible para ayudarme a comenzar. –
@Thomas Owens: No creo que el contenido de ningún libro esté disponible de forma gratuita en línea. El enlace de Sinan a Perl :: Critic es bueno. Otra opción es echar un vistazo a la documentación de algunos de los módulos centrales de CPAN. Aunque los enfoques pueden variar un poco, hay secciones estándar, etc. que son útiles como pautas. –