Docstring Python

A documentação é essencial para qualquer programação compreender o código facilmente. É usado para explicar o propósito de usar qualquer instrução ou função ou classe ou módulo no programa. Ajuda o codificador principal a lembrar a função de qualquer código depois de muito tempo e também ajuda outros programadores que desejam trabalhar no mesmo projeto. O codificador usa uma única linha de comentário para explicar brevemente a parte específica da função do código. A string de documento Python ou docstring é usada para explicar a função de um segmento particular do código em detalhes. A linha docstring deve começar com a letra maiúscula e terminar com um ponto. A primeira linha do docstring contém uma breve descrição da documentação geral. A segunda linha da docstring deve estar em branco para a grande docstring com várias linhas. Aspas simples triplas ('”) ou aspas duplas triplas (“” ”) são usados ​​para definir a docstring em Python. O conteúdo docstring pode ser acessado usando o __doc__ atributo do objeto e usando o ajuda() método. A maneira de declarar e acessar docstring em Python foi mostrada neste tutorial.

Exemplo-1: Acessando docstring de uma função usando __doc__ atributo

A maneira de declarar e acessar a docstring de uma função personalizada é mostrada no seguinte script. O seguinte script calcula o xⁿ onde x e n serão retirados do usuário. Poder () função definida no script para fazer a tarefa. Aqui, a docstring foi definida para esta função. __doc__ atributo foi usado no script para imprimir a docstring com a saída.

potência def (x, n):
"Calcule x elevado à potência n
Leia os valores de x e n dos argumentos da função
e Calcule e retorne o valor de x à potência n."
retornar x ** n
# Pegue o valor de x
x = int (input ('Insira o valor de x:'))
# Pegue o valor de n
n = int (input ('Insira o valor de n:'))
# Imprime o valor de retorno da função
print ("O% d à potência% d =% d"% (x, n, potência (x, n)))
# Imprima o valor docstring
print ("O conteúdo da docstring: \ n" + poder.__doc__)

Resultado:

A seguinte saída aparecerá após a execução do script acima.

Exemplo 2: Acessando docstring de classe e método usando ajuda() método

A maneira de declarar e acessar a docstring do documento e os métodos dessa classe são mostrados no seguinte script. A principal função do script é classificar uma lista numérica e reverter os dados da lista. Uma lista numérica de 8 elementos foi declarada na classe, e a docstring foi definida no início da classe usando aspas simples triplas. O método sort_list () foi definido na classe para imprimir os dados classificados da lista, e o documento definiu isso para este método. reverse_list () método é definido para imprimir os dados invertidos da lista, e a docstring também foi definida para este método. ajuda() método chamou três vezes no final do script para imprimir a docstring do list_operations aula, sort_list () método, e o reverse_list () método.

class list_operations:

class list_operations:
"
Classificando e invertendo os dados da lista
A classe contém dois métodos,
método sort_list () irá classificar e imprimir a lista,
método sort_reverse () irá reverter e imprimir a lista.
"
# Defina uma lista de dados numéricos
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (self):
"
Imprime os valores da lista após a classificação
A função pegará um objeto de lista de dados numéricos do argumento,
classifique os valores da lista usando o método sort ()
e imprimir os valores da lista classificada.
"
# Classifique a lista
auto.listdata.ordenar()
# Imprime a lista classificada usando loop
print ("Os valores da lista classificada: \ n")
pelo valor em si mesmo.listdata:
imprimir (valor, "", fim = ")
def reverse_list (self):
"
Imprima os valores da lista após reverter
A função pegará um objeto de lista de dados numéricos do argumento,
inverta os valores da lista usando o método reverse ()
e imprimir os valores da lista invertida.
"
# Inverta a lista
auto.listdata.marcha ré()
# Imprime a lista invertida usando loop
print ("Os valores da lista classificada: \ n")
pelo valor em si mesmo.listdata:
imprimir (valor, "", fim = ")
# Imprime o valor docstring da classe
ajuda (list_operations)
# Crie o objeto da classe
obj = list_operations ()
# Imprime o valor docstring do método particular
ajuda (obj.sort_list)
# Chame o método para imprimir a lista classificada
obj.sort_list ()

Resultado:

A seguinte saída aparecerá após a execução do script. Todos os docstring do script foram impressos para o primeiro ajuda() função. O docstring do sort_list () método foi impresso para o segundo ajuda() função.

Exemplo-3: Acessando docstring do módulo Python integrado

Nos exemplos anteriores, a docstring foi usada em classes e funções definidas pelo usuário. Cada módulo Python embutido e classe tem sua docstring que explica o propósito de usar aquele módulo ou função em particular. O codificador do módulo ou função define a docstring para tornar o código compreensível para os usuários. O script a seguir imprimirá a docstring predefinida do módulo datetime usando o ajuda() função.

# Importar módulo datetime
importar data e hora
# Mostra a docstring de datetime
ajuda (data e hora)

Resultado:

A seguinte saída aparecerá após a execução do script. A docstring do módulo datetime mostra a documentação detalhada do mesmo para ajudar os outros a conhecer as funções das classes e métodos definidos neste módulo de forma adequada.

Conclusão:

A documentação adequada é essencial quando qualquer módulo ou função é implementado para o propósito específico para ajudar o outro codificador a usar o módulo em seu código para fazer a tarefa específica. Se a documentação não estiver devidamente definida para o módulo ou função, os outros usuários terão problemas para usá-la. Então, cada codificador tem que usar a docstring do documento para fornecer informações detalhadas para que os outros entendam o código.