Resumo: neste tutorial, você aprenderá como usar docstrings para adicionar documentação a uma função.
Introdução à função help()
O Python fornece uma função interna chamada help() que permite mostrar a documentação de uma função.
O exemplo a seguir mostra a documentação da função print():
help(print)Saída:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
Observe que você pode usar a função help() para mostrar a documentação de módulos, classes, funções e palavras-chave. Este tutorial se concentra apenas na documentação das função.
Usando docstrings para documentar funções
Para documentar suas funções, você pode usar docstrings. O PEP 257 fornece as convenções docstring.
Quando a primeira linha no corpo da função for uma string, o Python a interpretará como uma docstring. Por exemplo:
def add(a, b):
"Return the sum of two arguments"
return a + b
E você pode usar a função help() para encontrar a documentação da função add():
help(add)Saída:
add(a, b)
Return the sum of two argumentsNormalmente, você usa docstrings de várias linhas:
def add(a, b):
""" Add two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
"""
return a + bSaída:
add(a, b)
Add the two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
Python armazena as docstrings na propriedade __doc__ da função.
O exemplo a seguir mostra como acessar a propriedade __doc__ da função add():
add.__doc__Resumo
- Use a função
help()para obter a documentação de uma função. - Coloque uma string, strings de uma ou várias linhas, como a primeira linha na função para adicionar documentação a ela.
