CKTIS / Python
docstring — cadeia de documentação
Um docstring é um literal de cadeia de caracteres comum (não uma f-string nem uma t-string), usado como primeira instrução de um módulo, de uma classe ou de uma função. Documenta a finalidade do objeto e está disponível através de __doc__; não é um comentário iniciado por #.
Versão: Python 3.14; repository image, production runtime not attested
Sintaxe
def function_name():
"""Describe the function's purpose."""
passUm docstring é um literal de cadeia de caracteres comum (não uma f-string nem uma t-string), que aparece como primeira instrução de um módulo, de uma classe ou de uma função, incluindo métodos. O Python disponibiliza-o como atributo __doc__ do objeto. As ferramentas podem utilizar este conteúdo para apresentar documentação.
Nem um literal de cadeia formatada (f-string) nem um literal de cadeia de modelo (t-string) cria um docstring, mesmo que o literal não contenha campos de substituição e seja a primeira instrução. Se a primeira instrução de uma função for f"""Description.""", o seu atributo __doc__ tem o valor None.
Um comentário iniciado por # não cria um docstring. Um literal de cadeia isolado colocado depois de outra instrução também não se torna o docstring principal do objeto. As aspas triplas """...""" são práticas, sobretudo para várias linhas, mas não bastam por si só: tanto o tipo de literal como a sua posição são determinantes.
Por convenção, a primeira linha deve descrever brevemente a finalidade do objeto, começar com uma letra maiúscula e terminar com um ponto final. Separe a descrição adicional com uma linha em branco; explique os argumentos, os resultados e os efeitos secundários quando necessário. Estas são recomendações relativas ao conteúdo, não requisitos de sintaxe.
No exemplo, square.__doc__ disponibiliza a descrição, enquanto square(5) calcula o resultado independentemente da documentação. A opção -OO remove os docstrings, pelo que o código da aplicação não deve depender da sua presença.
Exemplos
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Resultado
Return the square of number. 25
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.