Migración desde Javadoc a la documentación de Python

Question

Así que he llegado un poco acostumbrado a la documentación Javadoc estilo. Mirando a través de varios ejemplos de código Python, estoy encontrando que, a primera vista, la documentación parece que falta mucha información.

Lo bueno: raramente varían hacer nota trozos evidentes de documentación. Las cadenas de documentación son por lo general un párrafo o menos marcado de Inglés que se integra en lugar de sobresalir en líneas separadas.

Lo malo: en conjunción con pato tipificación de Python, me parece que muchas funciones no están claras acerca de los parámetros que esperan. No hay ningún tipo insinuando (pato-insinuando?) Y muchas veces sería bueno tener una idea de que el parámetro debe ser similar a la lista, en forma de hilo, secuencia similar.

Por supuesto, Javadoc fue diseñado para un lenguaje de bajo nivel, sin grandes capacidades de introspección de Python, lo que podría explicar la filosofía de documentación menos detallado.

Cualquier consejo sobre las normas de documentación de Python y las mejores prácticas?

Answer 1

El href="http://docutils.sourceforge.net/rst.html" rel="noreferrer"> reStructuredText formato fue diseñado en respuesta a la necesidad de documentación de Python que podría ser embebido en docstrings, así que lo mejor es a cursos de reST y formatear el docstrings con ese formato . Usted puede encontrar, como yo, que luego pasan a formato sólo de cualquier documentación en reposo, pero eso es un punto de lado: -)

Para documentar específicamente su código Python, el href="http://sphinx.pocoo.org/" rel="noreferrer"> Sphinx sistema Esfinge permite una documentación muy bien estructurado de código fuente , incluyendo, por supuesto, las características específicas de las firmas de función, que está pidiendo. Permite una suite amplia documentación que se construirá, tanto de auto-extraído y escrito a mano, utilizando el mismo sistema de formato.

Si solamente ¿Quieres documentación generada a partir del código fuente, a continuación, Epydoc va a extraer documentación de la API a partir del código fuente ; él, también, lee reST formato para el texto.