Resumo : neste tutorial, você aprenderá como usar docstrings para adicionar documentação a uma função.
Introdução à função help()
Python fornece uma função integrada chamada help()
que permite mostrar a documentação de uma função .
O exemplo a seguir mostra a documentação da print()
função:
help(print)
Linguagem de código: Python ( python )
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.
Linguagem de código: Python ( python )
Observe que você pode usar a help()
função para mostrar a documentação de módulos , classes , funções e palavras-chave. Este tutorial se concentra apenas na documentação de funções.
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 irá interpretá-la como uma docstring. Por exemplo:
def add(a, b):
"Return the sum of two arguments"
return a + b
Linguagem de código: Python ( python )
E você pode usar a help()
função para encontrar a documentação da add()
função:
help(add)
Linguagem de código: Python ( python )
Saída:
add(a, b)
Return the sum of two arguments
Linguagem de código: Python ( python )
Normalmente, você usa docstrings multilinhas:
def add(a, b):
""" Add two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
"""
return a + b
Linguagem de código: Python ( python )
Saída:
add(a, b)
Add the two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
Linguagem de código: Sessão Shell ( shell )
Python armazena os docstrings na __doc__
propriedade da função.
O exemplo a seguir mostra como acessar a __doc__
propriedade da add()
função:
add.__doc__
Linguagem de código: Python ( python )
Resumo
- Use a
help()
função para obter a documentação de uma função. - Coloque uma string, seja de linha única ou de múltiplas linhas, como a primeira linha na função para adicionar documentação a ela.