Migrando de documentação Javadoc para Python

Question

Então, eu fui um pouco acostumado com a documentação do estilo Javadoc. Olhando através de vários exemplos de código Python, estou descobrindo que, à primeira vista, a documentação parece estar faltando muita informação.

O bem: Vary raramente você vê pedaços de documentação evidentes. Os Docstrings geralmente são um parágrafo ou menos marcação em inglês que se integra em vez de se destacar em linhas separadas.

O ruim: em conjunto com o pato de Python, acho que muitas funções não são claras sobre os parâmetros que eles esperam. Não há um tipo de sugestão de tipo (cancelamento de pato?) E muitas vezes seria bom ter uma idéia de que o parâmetro seja semelhante a uma lista, semelhante a uma corda, semelhante a um fluxo.

Obviamente, o Javadoc foi projetado para uma linguagem de nível inferior, sem grandes habilidades de introspecção do Python, o que pode explicar a filosofia de documentação menos detalhada.

Algum conselho sobre os padrões de documentação do Python e as melhores práticas?

Answer 1

o reestruturado text O formato foi projetado em resposta à necessidade de documentação python que poderia ser incorporada em documentos, então a melhor coisa é Aprenda descanso e formate seus documentos com esse formato. Você pode achar, como eu, que você então formou quase algum Documentação em repouso, mas esse é um ponto lateral :-)

Para documentar especificamente seu código python, o Esfinge O sistema é um conjunto de extensões para o formato restante e um sistema de construção para renderizar documentos. Como foi projetado para documentar o próprio Python, incluindo a biblioteca padrão, Esfinge permite documentação muito bem estruturada do código-fonte, incluindo, é claro, as especificidades das assinaturas de funções que você está perguntando. Ele permite que um conjunto abrangente de documentação seja construído, tanto extraído automaticamente quanto escrito à mão, todos usando o mesmo sistema de formatação.

Se você só deseja documentação gerada pelo seu código -fonte, então Epydoc Extrairá a documentação da API do seu código -fonte; Também lê formatação de repouso para o texto.