que - ¿Cuál es la mejor manera de documentar el código Perl?
mongodb español (8)
¿Alguna sugerencia sobre cómo puedo documentar mi código Perl? ¿Qué usas y qué herramientas están disponibles para ayudarme?
¿Qué módulo usas para convertir pod a html?
¿Qué módulo usas para convertir pod a html?
Echa un vistazo a Pod::ProjectDocs : obtienes una utilidad de línea de comandos simple que convertirá todo el POD en tu proyecto Perl en un conjunto de páginas HTML que se vean exactamente como lo que ves en search.cpan.org .
Definitivamente recomiendo POD .
POD también se puede usar en línea con el código, pero prefiero ponerlo al final del programa después de __END__ (como recomienda Damian Conway en Perl Best Practices ).
Mire POD::Server & POD::Webserver , que proporciona un front-end web para todos sus POD.
Nadie mencionó Smart::Comments ¿ Smart::Comments ? No siempre es lo que quieres, pero es bueno si necesitas más poder para los comentarios.
No se debe voltear demasiado, pero la mejor manera de documentar el código de Perl es la misma que con el código del documento en cualquier otro idioma.
En cuanto a las herramientas específicas, utilizo una combinación de comentarios en línea estándar, pod para grandes cantidades de documentación donde un formato similar al hombre es apropiado, y TeX como respaldo final para documentos que necesitan ser más libres. (Y, en el espíritu de "igual que en cualquier otro idioma", sí, uso pod para documentar código que no sea de Perl).
También es posible que desee consultar Perl Best Practices por Damian Conway. Usé algunos de los consejos para limpiar una pequeña base de código de Perl que heredé.
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 ya puedes, como lo dijiste, POD después de FIN . 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?)
Así es como Mozilla documenta su Perl.
Mire dentro de casi cualquier módulo de Perl y verá el formato de Documentación antigua simple (POD) . En la search.cpan.org , cuando mira un módulo, tiene la opción de ver la fuente en bruto, de modo que puede ver el pod en bruto, pero también puede usar perldoc desde la línea de comando. El -m muestra el archivo
perldoc -m Foo::Bar
O bien, si desea encontrar el archivo para poder verlo en su editor favorito, use el -l para encontrarlo:
perldoc -l Foo::Bar
Una vez que comienza a documentar su programa, coloca el Pod en el archivo correcto con el código, ya sea entrelazado 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 tu propio Traductor de Pod es fácil con Pod::Simple , así que si no encuentras un traductor en tu forma final favorita, solo hazlo tú mismo.
También hay varias herramientas que puede agregar a su suite de pruebas para verificar su Pod. El módulo Test::Pod comprueba los errores de formato, el Test::Pod::Coverage comprueba que ha documentado cada subrutina, y así sucesivamente. También podría estar interesado en mi documentación de documentación de Perl .