A documentação é essencial para qualquer programação entender o código facilmente. É usado para explicar o objetivo de usar qualquer declaração ou função ou classe ou módulo no programa. Ajuda o codificador principal a lembrar a função de qualquer código após um longo tempo e também ajuda outros codificadores que desejam trabalhar no mesmo projeto. O codificador usa uma única linha de comentário para explicar a parte particular da função do código em breve. Python Document String ou docstring é usado para explicar a função de um segmento específico do código em detalhes. A linha Docstring deve começar com a letra maiúscula e terminar com um período. A primeira linha do docstring contém uma breve descrição da documentação geralmente. A segunda linha do Docstring deve estar em branco para o grande docstring de várias linhas.
Triple Single Quotes ('”) ou
Citações duplas triplas ("" ") são usados para definir o Docstring em Python. O conteúdo de 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 mostrou neste tutorial.
Exemplo 1: Acessando Docstring de uma função usando __doc__ atributo
A maneira de declarar e acessar o documento de uma função personalizada mostrou no script a seguir. O script a seguir calcula o xn onde x e n serão retirados do usuário. Poder () A função definiu no script para realizar a tarefa. Aqui, o docstring foi definido para esta função. __doc__ O atributo foi usado no script para imprimir o documento com a saída.
Def Power (x, n):
"Calcule x para a potência n
Leia os valores de x e n dos argumentos da função
e calcule e retorne o valor de x à energia n."
retornar x ** n
# Pegue o valor de x
x = int (entrada ('Digite o valor de x:'))
# Pegue o valor de n
n = int (entrada ('Digite o valor de n:')))
# Imprima o valor de retorno da função
print ("o %d para a potência %d = %d" %(x, n, potência (x, n))))
# Imprima o valor do documento
print ("o conteúdo do docstring: \ n" + poder.__doc__)
Saída:
A saída a seguir será exibida 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 o documento do documento e os métodos dessa classe mostrou no script a seguir. 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 o docstring foi definido no início da classe, usando citações únicas 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 () O método é definido para imprimir os dados invertidos da lista, e o docstring também foi definido para este método. ajuda() O método chamou três vezes no final do script para imprimir o documento do list_operations aula, Sort_List () método e o reverse_list () método.
Classe list_operations:
Classe list_operations:
"
Classificar e reverter os dados da lista
A classe contém dois métodos,
Método Sort_List () classificará e imprimirá a lista,
Método Sort_Reverse () 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):
"
Imprima os valores da lista após a classificação
A função levará um objeto de lista de dados numéricos do argumento,
Classifique os valores da lista usando o método Sort ()
e imprima os valores da lista classificada.
"
# Classifique a lista
auto.ListData.organizar()
# Imprima a lista classificada usando loop
print ("Os valores da lista classificada: \ n")
para valor em si mesmo.ListData:
Imprimir (valor, "", end = ")
def Reverse_list (self):
"
Imprima os valores da lista após a reversão
A função levará um objeto de lista de dados numéricos do argumento,
reverta os valores da lista usando o método reverse ()
e imprima os valores da lista invertida.
"
# Reverta a lista
auto.ListData.reverter()
# Imprima a lista invertida usando loop
print ("Os valores da lista classificada: \ n")
para valor em si mesmo.ListData:
Imprimir (valor, "", end = ")
# Imprima o valor do documento da classe
ajuda (list_operations)
# Crie objeto da classe
obj = list_operations ()
# Imprima o valor do documento do método específico
ajuda (obj.Sort_list)
# Ligue para o método para imprimir a lista classificada
obj.Sort_List ()
Saída:
A saída a seguir aparecerá após a execução do script. Todo o documento do script foi impresso para o primeiro ajuda() função. A documentação do Sort_List () o método foi impresso para o segundo ajuda() função.
Exemplo 3: Acessando o Doctring do módulo Python embutido
Nos exemplos anteriores, o docstring usou na classe e função definida pelo usuário. Todo módulo e classe python embutidos têm seu documento que explica o objetivo de usar esse módulo ou função específica. O codificador do módulo ou função define o DocString para tornar o código compreensível para os usuários. O script a seguir imprimirá o documento predefinido do módulo DateTime usando o ajuda() função.
# Importar módulo DATETIME
importar datetime
# Exiba a documentação do DateTime
Ajuda (DateTime)
Saída:
A saída a seguir será apareceu após a execução do script. A documentação do módulo DateTime mostra a documentação detalhada dele para ajudar os outros a conhecer as funções das classes e métodos definidos neste módulo corretamente.
Conclusão:
A documentação adequada é essencial quando qualquer módulo ou função é implementado com o objetivo específico de ajudar o outro codificador a usar o módulo em seu código para realizar a tarefa específica. Se a documentação não for definida corretamente para o módulo ou função, os outros usuários enfrentarão problemas. Portanto, todo codificador deve usar o documento do documento para fornecer informações detalhadas para os outros entenderem o código.