2.8 Strings de documentação

Um recurso especialmente útil em Python é o suporte nativo à documentação de código por meio de strings localizadas estrategicamente, chamadas docstrings. Módulos, classes, funções e até propriedades podem ser descritas por meio de docstrings; o exemplo a seguir demonstra um módulo hipotético, financ.py, documentado adequadamente:

    """Módulo que contém funções financeiras."""

    def calcula_juros(valor, taxa=0.1):
        """Calcula juros sobre um valor.

        Aplica uma taxa de juros fornecida sobre um valor 
        e retorna o resultado. Se omitida a taxa, o valor 
        0.1 será utilizado""" 
        # ...

    class Pagamento:
        """Classe que representa um pagamento a ser efetuado.

        Inclui informações de crédito e débito. Permite efetuar
        operações como devolução, cancelamento, transferência e
        pagamento em si. Possui o seguinte ciclo de vida: 
        ...
        """

As docstrings do módulo acima podem ser visualizadas em tempo de execução, e mesmo a partir do modo interativo do interpretador por meio da função help() e do atributo __doc__:

    >>> import financ
    >>> help(calcula_juros)
    Calcula juros sobre um valor.

        Aplica uma taxa de juros fornecida sobre um valor 
        e retorna o resultado. Se omitida a taxa, o valor 
        0.1 será utilizado

    >>> print financ.__doc__
    Módulo que contém funções financeiras.

Observe que a função help recebe como argumento a própria função calcula_juros; pode parecer pouco usual mas é um padrão comum em Python.

Este recurso é extremamente útil para o aprendizado da linguagem quando explorando objetos pré-definidos; utilize-o sempre que estiver necessitando de uma referência rápida:

    >>> len([1,2,3])
    3
    >>> help(len)
    Help on built-in function len:

    len(...)
        len(object) -> integer
            
        Return the number of items of a sequence or mapping.

Docstrings podem também ser processadas utilizando ferramentas externas, como o epydoc¹¹, gerando referências em formatos navegáveis como HTML.

2.8 Strings de documentação

Notas de rodapé