docstrings

Docstrings são strings que inserimos dentro de nosso código Python com o intuito de fornecer uma explicação sobre o funcionamento deste. Essa string deve ser colocada como a primeira linha da definição de uma classe, método ou função.

O texto representado por tal string será apresentado quando for executado o comando help() utilizando como entrada a função onde a docstring está inserida. Considere o exemplo da função dobro:

def dobro(x):
    """Esta função retorna o dobro do número x"""
    return x*2

Quando executarmos o comando help sobre a função acima, receberemos o conteúdo da string colocada como a primeira linha:

>>> help(dobro)
Help on function dobro in module __main__:

dobro(x)
    Esta função retorna o dobro do número x

A string inserida como docstring também pode ser acessada através do atributo __doc__ daquela função:

>>> print dobro.__doc__
Esta função retorna o dobro do número x

Isso vale também para classes e métodos:

 class Data:
     """Classe utilizada para a representação de datas.
     As datas são representadas no formato dia, mês e ano.
     """
     ...
     def passaDia(self):
         """Acrescenta um dia na data."""
         ...

Ao invocarmos o comando help sobre a classe Data, obteremos o seguinte resultado:

>>> help(Data)
Help on class Data in module __main__:

class Data
 |  Classe utilizada para a representação de datas.
 |  As datas são representadas no formato dia, mês e ano.
 | 
 |  Methods defined here:
 | 
 |  passaDia(self)
 |      Acrescenta um dia na data.

Dúvidas sobre o que e como colocar em uma docstring? Consulte a PEP 257 (PEP é a sigla referente a: Python Enhancement Proposals).

• docstrings
• documentação
• python