¿Alguna sugerencia sobre cómo puedo documentar mi código Perl? ¿Qué usas y qué herramientas están disponibles para ayudarme?¿Cuál es la mejor manera de documentar el código de Perl?
¿Qué módulo usas para convertir pod a html?
Mire dentro de casi cualquier módulo Perl y verá el formato Plain Old Documentation (POD). En CPAN Search, al mirar un módulo tiene la opción de ver la fuente sin formato, de modo que puede ver el pod en bruto, pero también puede usar perldoc desde la línea de comando. El interruptor -m muestra el archivo
perldoc -m Foo::Bar
O, si se quiere encontrar el archivo para que pueda verlo en su editor favorito, utilice el interruptor -l para encontrarlo:
perldoc -l Foo::Bar
vez usted comienza a documentar su programa, coloca el Pod en el archivo junto con el código, ya sea entretejido con el código para que la documentación esté junto a las partes relevantes, o al principio, en el medio o al final como una gran parte.
Pod se puede traducir fácilmente a muchos otros formatos, como LaTeX, Postscript, HTML, etc. con traductores que vienen con Perl (pod2latex, pod2ps, pod2html). Incluso tengo un traductor de vainas que va a InDesign. Escribir su propio traductor de Pod es fácil con Pod::Simple, por lo que si no encuentra un traductor en su forma final favorita, solo hágalo usted mismo.
También hay varias herramientas que puede agregar a su suite de pruebas para verificar su Pod. El módulo Test::Pod comprueba errores de formato, el módulo Test::Pod::Coverage comprueba que ha documentado cada subrutina, y así sucesivamente. También podría estar interesado en mi Perl documentation documentation.
Así documenta Mozilla su Perl.
No se debe voltear demasiado, pero la mejor manera de documentar el código Perl es de la misma manera que con el código del documento en cualquier otro idioma.
En cuanto a herramientas específicas, utilizo una mezcla de comentarios en línea estándar, vaina de trozos más grandes de la documentación en un formato similar al hombre es apropiado, y Tex Como opción final para los documentos que necesitan para ser más libre. (Y, en el espíritu de "igual que en cualquier otro idioma", sí, uso pod para documentar código que no sea de Perl.)
Definitivamente recomiendo POD.
POD también se puede utilizar en línea con el código, pero prefiero ponerlo en la parte inferior del programa después de __END__ (como lo recomendó Damian Conway en Perl Best Practices).
Mire POD::Server & POD::Webserver, que proporciona un front-end web para todos sus POD.
¿Qué módulo usas para convertir el pod a html?
Salida Pod::ProjectDocs - se obtiene una utilidad de línea de comandos sencilla que convertirá todo el POD en su proyecto de Perl en un conjunto de páginas HTML que se parecen a lo que se ve en search.cpan.org.
Ahora los días en algunos casos es Hande [Mojolicious :: Plugin :: PODRenderer] (http://mojolicious.org/perldoc/Mojolicious/Plugin/PODRenderer) –
Quizás también desee comprobar Perl Best Practices por Damian Conway. Usé algunos de los consejos para limpiar una pequeña base de código de Perl que heredé.
Nadie mencionó Smart::Comments? No siempre es lo que quieres, pero es bueno si necesitas más poder para los comentarios.
Este módulo es increíble. Un poco sorprendido de que nunca lo haya escuchado antes. No puedo decirle cuántas veces he escrito subrutinas para hacer partes de lo que este módulo puede ofrecer, no puedo recomendarlo lo suficiente. – slm
documentos de usuario y codificadores separados. tal vez ponga los documentos de usuario (tuts, faq, reference) en su directorio (/ doc) y codificadores en el mismo código. lamentablemente se espera por convención, tener una visión general en el módulo en sí. esto puede, como ya se indicó, hacerlo POD después de END. los documentos de codificación de melena pueden poner en comentarios. cosas adicionales como estilo de codificación o cómo contribuir poner en archivos .pod separados dentro de la base de código (directorio raíz?)
De gustibus. Personalmente prefiero Doxygen (Doxygen :: Filter :: Perl) a POD. –