4.7.6 Documentation Strings

Existem algumas convenções comuns para o conteúdo e formatação de cadeias de documentação.

A primeira linha deve ser sempre um resumo curto e conciso do propósito do objeto. Por uma questão de brevidade, não deve declarar explicitamente o nome ou o tipo do objeto, uma vez que estes estão disponíveis por outros meios (exceto se o nome for um verbo descrevendo a operação de uma função). Essa linha deve começar com uma letra maiúscula e terminar com um período.

Se houver mais linhas na seqüência de documentação, a segunda linha deverá estar em branco, separando visualmente o resumo do resto da descrição. As linhas a seguir devem ser um ou mais parágrafos descrevendo as convenções de chamada do objeto, seus efeitos colaterais, etc.

O analisador Python não tira a indentação de literais de seqüência de caracteres de várias linhas no Python, portanto, as ferramentas que processam a documentação precisam remover a indentação, se desejado. Isso é feito usando a seguinte convenção. A primeira linha não em branco após a primeira linha da cadeia determina a quantidade de recuo para toda a cadeia de documentação. (Não podemos usar a primeira linha, pois ela é geralmente adjacente às aspas de abertura da string, portanto, seu recuo não é aparente na string literal). Espaços em branco “equivalentes” a essa indentação são removidos do início de todas as linhas da string . Linhas que são recuadas menos não devem ocorrer, mas se ocorrerem, todos os espaços em branco iniciais deverão ser removidos. A equivalência de espaço em branco deve ser testada após a expansão das guias (para 8 espaços, normalmente).

Aqui está um exemplo de uma docstring de várias linhas:

    >>> def my_function():
    ...     """Do nothing, but document it.
    ... 
    ...     No, really, it doesn't do anything.
    ...     """
    ...     pass
    ... 
    >>> print my_function.__doc__
    Do nothing, but document it.
    
        No, really, it doesn't do anything.
Anúncios

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair /  Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair /  Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair /  Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair /  Alterar )

Conectando a %s