Cadena de documentación de Python

La documentación es fundamental para que cualquier programador comprenda el código fácilmente. Se utiliza para explicar el propósito de usar cualquier declaración o función o clase o módulo en el programa. Ayuda al codificador principal a recordar la función de cualquier código después de mucho tiempo, y también ayuda a otros codificadores que quieren trabajar en el mismo proyecto. El codificador utiliza una sola línea de comentario para explicar brevemente la parte particular de la función del código. La cadena de documentos de Python o la cadena de documentos se utilizan para explicar la función de un segmento particular del código en detalle. La línea de la cadena de documentos debe comenzar con la letra mayúscula y terminar con un punto. La primera línea de la cadena de documentos contiene una breve descripción de la documentación en general. La segunda línea de la cadena de documentos debe estar en blanco para la cadena de documentos grande de varias líneas. Comillas simples triples ('”) o comillas dobles triples ("" ") se utilizan para definir la cadena de documentos en Python. Se puede acceder al contenido de la cadena de documentos usando El documento__ atributo del objeto y utilizando el ayuda() método. La forma de declarar y acceder a la cadena de documentos en Python se muestra en este tutorial.

Ejemplo-1: Accediendo a la cadena de documentos de una función usando __Doc__ atributo

La forma de declarar y acceder a la cadena de documentos de una función personalizada se muestra en el siguiente script. El siguiente script calcula la x^norte donde xyn se tomarán del usuario. Energía () La función ha definido en el script para realizar la tarea. Aquí, la cadena de documentación se ha definido para esta función. __Doc__ El atributo se ha utilizado en el script para imprimir la cadena de documentos con la salida.

def potencia (x, n):
"Calcula x elevado a la potencia n
Leer los valores de xyn de los argumentos de la función
y Calcule y devuelva el valor de x elevado a n."
devuelve x ** n
# Toma el valor de x
x = int (input ('Ingrese el valor de x:'))
# Toma el valor de n
n = int (input ('Ingrese el valor de n:'))
# Imprime el valor de retorno de la función
print ("El% d a la potencia% d =% d"% (x, n, potencia (x, n)))
# Imprime el valor de la cadena de documentos
print ("El contenido de la cadena de documentos: \ n" + poder.__Doc__)

Producción:

La siguiente salida aparecerá después de ejecutar el script anterior.

Ejemplo-2: Accediendo a la cadena de documentos de la clase y el método usando ayuda() método

La forma de declarar y acceder a la cadena de documentos del documento y los métodos de esa clase se muestran en el siguiente script. La función principal del script es ordenar una lista numérica e invertir los datos de la lista. Se ha declarado una lista numérica de 8 elementos en la clase y la cadena de documentación se ha definido al principio de la clase mediante el uso de comillas simples triples. El método sort_list () se ha definido en la clase para imprimir los datos ordenados de la lista, y el documento ha definido esto para este método. lista_inversa () El método está definido para imprimir los datos invertidos de la lista, y la cadena de documentos también se ha definido para este método. ayuda() ha llamado tres veces al final del script para imprimir la cadena de documentos del lista_operaciones clase, Lista Ordenada() método, y el lista_inversa () método.

class list_operations:

class list_operations:
"
Ordenar e invertir los datos de la lista
La clase contiene dos métodos,
El método sort_list () ordenará e imprimirá la lista,
El método sort_reverse () invertirá e imprimirá la lista.
"
# Definir una lista de datos numéricos
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (yo):
"
Imprima los valores de la lista después de ordenar
La función tomará un objeto de lista de datos numéricos del argumento,
ordenar los valores de la lista usando el método sort ()
e imprime los valores de la lista ordenada.
"
# Ordenar la lista
uno mismo.listdata.clasificar()
# Imprime la lista ordenada usando loop
print ("Los valores de la lista ordenada: \ n")
por valor en uno mismo.listdata:
print (valor, "", end = ")
def lista_inversa (yo):
"
Imprima los valores de la lista después de invertir
La función tomará un objeto de lista de datos numéricos del argumento,
invertir los valores de la lista usando el método reverse ()
e imprime los valores de la lista invertida.
"
# Invierta la lista
uno mismo.listdata.contrarrestar()
# Imprime la lista invertida usando loop
print ("Los valores de la lista ordenada: \ n")
por valor en uno mismo.listdata:
print (valor, "", end = ")
# Imprime el valor de la cadena de documentos de la clase
ayuda (lista_operaciones)
# Crear objeto de la clase
obj = lista_operaciones ()
# Imprime el valor de la cadena de documentos del método en particular
ayuda (obj.Lista Ordenada)
# Llame al método para imprimir la lista ordenada
obj.Lista Ordenada()

Producción:

La siguiente salida aparecerá después de ejecutar el script. Toda la cadena de documentos del script se imprimió por primera vez ayuda() función. La cadena de documentos del Lista Ordenada() El método se ha impreso para el segundo ayuda() función.

Ejemplo-3: Acceder a la cadena de documentos del módulo Python integrado

En los ejemplos anteriores, la cadena de documentos se ha utilizado en funciones y clases definidas por el usuario. Cada módulo y clase de Python incorporado tiene su cadena de documentos que explica el propósito de usar ese módulo o función en particular. El codificador del módulo o función define la cadena de documentos para que el código sea comprensible para los usuarios. El siguiente script imprimirá la cadena de documentos predefinida del módulo de fecha y hora utilizando el ayuda() función.

# Importar módulo de fecha y hora
importar fecha y hora
# Mostrar la cadena de documentos de fecha y hora
ayuda (fecha y hora)

Producción:

La siguiente salida aparecerá después de ejecutar el script. La cadena de documentos del módulo datetime muestra la documentación detallada del mismo para ayudar a los demás a conocer las funciones de las clases y métodos definidos en este módulo correctamente.

Conclusión:

La documentación adecuada es esencial cuando cualquier módulo o función se implementa con el propósito específico de ayudar al otro codificador a usar el módulo en su código para realizar la tarea en particular. Si la documentación no está definida correctamente para el módulo o la función, los otros usuarios tendrán problemas para usarla. Por lo tanto, cada codificador debe usar la cadena de documentos del documento para proporcionar información detallada para que los demás comprendan el código.