O que colocar em uma docstring de módulo python? [fechadas]

167

Ok, então eu li o PEP 8 e o PEP 257 e escrevi muitos documentos para funções e classes, mas estou um pouco inseguro sobre o que deve acontecer em um módulo de documentação. Achei que, no mínimo, deveria documentar as funções e classes que o módulo exporta, mas também vi alguns módulos que listam nomes de autores, informações sobre direitos autorais, etc. Alguém tem um exemplo de como uma boa documentação em python deve ser estruturado?

python documentation module

Respostas:

183

Pense em alguém que help(yourmodule)esteja fazendo o prompt do intérprete interativo - o que eles querem saber? (Outros métodos de extrair e exibir as informações são aproximadamente equivalentes helpem termos de quantidade de informações). Então, se você tem x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

então:

>>> import x; help(x)

mostra:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

Como você vê, as informações detalhadas sobre as classes (e também sobre as funções, embora não esteja mostrando uma aqui) já estão incluídas nos documentos desses componentes; a própria documentação do módulo deve descrevê-los muito sumariamente (se houver) e concentrar-se em um resumo conciso do que o módulo como um todo pode fazer por você, idealmente com alguns exemplos testados (exatamente como funções e classes idealmente deveriam ter exemplos testados em suas doutrinas).

Não vejo como os metadados, como o nome do autor e os direitos autorais / licença, ajudam o usuário do módulo - ele pode entrar nos comentários, pois pode ajudar alguém a considerar se deve ou não reutilizar ou modificar o módulo.

— Alex Martelli
fonte

Portanto, é habitual incluir autor, direitos autorais etc. nos comentários na parte superior de um módulo?

@ 007brendan, é prática bastante comum, sim.

— Alex1801

@IfLoop Duvido que haja mais usuários que usam o help()método no intérprete do que usuários que simplesmente leem o código.

— confused00

Tenha em mente que a coisa mais importante a ser documentada é o porquê . Documentar o que algo faz é o trabalho de um código bem escrito. Documentar por que é o trabalho da documentação.

— Erik Aronesty 03/09/19

Para citar as especificações :

A documentação de um script (um programa independente) deve ser utilizável como mensagem de "uso", impressa quando o script é chamado com argumentos ausentes ou incorretos (ou talvez com a opção "-h" para "ajuda"). Essa documentação deve documentar a função do script e sintaxe da linha de comando, variáveis de ambiente e arquivos. As mensagens de uso podem ser bastante elaboradas (várias telas cheias) e devem ser suficientes para um novo usuário usar o comando corretamente, bem como uma referência rápida completa a todas as opções e argumentos para o usuário sofisticado.

A docstring para um módulo geralmente deve listar as classes, exceções e funções (e quaisquer outros objetos) exportadas pelo módulo, com um resumo de uma linha de cada um. (Esses resumos geralmente fornecem menos detalhes do que a linha de resumo na documentação do objeto.) A documentação de um pacote (ou seja, a documentação do __init__.pymódulo do pacote ) também deve listar os módulos e subpacotes exportados pelo pacote.

A documentação de uma classe deve resumir seu comportamento e listar os métodos públicos e variáveis de instância. Se a classe tiver a intenção de ser subclassificada e tiver uma interface adicional para subclasses, essa interface deverá ser listada separadamente (na documentação). O construtor da classe deve ser documentado na documentação para seu __init__método. Métodos individuais devem ser documentados por sua própria doutrina.

A sequência de uma função ou método é uma frase que termina em um ponto. Ele prescreve o efeito da função ou do método como um comando ("Faça isso", "Retorne isso"), não como uma descrição; por exemplo, não escreva "Retorna o nome do caminho ...". Uma doutrina de várias linhas para uma função ou método deve resumir seu comportamento e documentar seus argumentos, valor (es) de retorno, efeitos colaterais, exceções levantadas e restrições sobre quando pode ser chamado (todos, se aplicável). Argumentos opcionais devem ser indicados. Deve ser documentado se os argumentos da palavra-chave fazem parte da interface.

— Remi
fonte