Cadena de documentación NumPy

Como ya sabemos cómo escribir los comentarios de varias líneas, podemos usar comillas simples triples o comillas dobles triples. Usamos una cadena de documentación cuando queremos describir nuestras funciones para que podamos obtener la documentación cuando la necesitemos. Algunos IDE le brindan documentación con solo pasar el mouse sobre el nombre y algunos resaltan ciertas palabras clave. Pero el hecho es que las cadenas de documentación en NumPy son mucho más flexibles que en otros idiomas. Docstring es un literal de cadena que aparece al comienzo de la definición de la función. Tenemos que proporcionar valores específicos al usar las cadenas de documentación en casos de funciones, clases, etc.

Cuando usamos docstrings con funciones, tenemos que pasar los argumentos. Al usarlos con clases, pasamos los atributos y métodos. En el caso de los Módulos, tenemos que proporcionar una lista de clases y funciones. En el caso del paquete, pasamos la lista de módulos con funcionalidad. Básicamente, el propósito de la cadena de documentación es, como su nombre lo explica, ayudar con la documentación de nuestro código. Hacemos documentación para que si alguien usa nuestro código en el futuro, pueda entender nuestro código y la lógica detrás de nuestro código con la ayuda de docstring. Las funciones integradas también tienen cadenas de documentación; podemos usar la función de ayuda () para ver la cadena de documentación de las funciones integradas.

Hay algunas diferencias entre los comentarios y las cadenas de documentación. Los intérpretes ignoran los comentarios, pero los intérpretes no ignoran las cadenas de documentación. La memoria se asigna para docstrings. Un comentario es una descripción del código pero, por otro lado, las cadenas de documentación nos dicen el propósito del código.

Sintaxis:

La sintaxis para escribir las cadenas de documentación en NumPy es:

Tenga en cuenta que docstring no es una función o método, por lo que no tiene la sintaxis adecuada. Lo único a tener en cuenta aquí es que comenzamos la cadena de documentación con tres comillas simples o tres comillas dobles. Escribimos nuestra descripción del código y lo terminamos nuevamente con tres comillas simples o tres comillas dobles al final. No hay nada obligatorio que escribir para docstrings. Solo tiene que poner tres comillas simples o dobles antes y después de la descripción de su cadena.

Ejemplo 1:

Para comprender mejor las cadenas de documentos, realicemos un ejemplo. En este ejemplo, después de incluir la biblioteca NumPy, simplemente declaramos la variable 'a' y otra variable 'b'. Después de eso, creamos nuestra cadena de documentación que dice 'Permítanos agregar las variables 'a' y 'b''. En nuestro caso, este es un ejemplo fácil, pero si nuestro código es complejo, esto ayuda mucho al codificador a comprender el código. Después de eso, sumamos las variables 'a' y 'b' y almacenamos su resultado de salida en otra variable que es 'c'. Finalmente, imprimimos el valor de la variable “c”. Ahora, ejecutamos nuestro código.

Esta es nuestra salida de la pieza de código dada. Podemos ver que el sistema no ha dado ningún error de sintaxis incorrecta ni nada por la línea 7 de nuestro código. Además, el sistema no ha impreso nuestra cadena de documentación. En cambio, solo imprimió la salida de nuestra variable 'c' en la que le dijimos a nuestro sistema que imprimiera. Esto muestra cómo funcionan las cadenas de documentación. La próxima vez, cuando un nuevo codificador intente trabajar en nuestro código, comprenderá lo que estamos haciendo con la ayuda de nuestra cadena de documentación. Pero no se imprimirá como salida, por lo que no molestará al usuario del código.

Ejemplo 2:

Ahora, realizamos un ejemplo complejo para comprender el funcionamiento de la cadena de documentación. Primero, incluimos la biblioteca NumPy y luego escribimos una cadena de documentación en la que explicamos la siguiente línea de código donde explicamos la inicialización de la matriz. También agregamos las cadenas de documentación en la otra parte del código. Ahora, si compartimos este código con cualquier nuevo desarrollador de Python sin agregar las cadenas de documentación, de alguna manera será difícil para él conocer el funcionamiento y el propósito de este código. Tiene que buscar primero sobre las funciones que usamos. Pero si agregamos una cadena de documentación a nuestro código, será fácil para los otros desarrolladores entender el código sin estudiar más sobre las funciones. No estamos restringidos a agregar comentarios a algunos límites; Los comentarios pueden ser de una o más líneas. También se puede agregar más de una vez en un código. Luego, importa NumPy como np.

Como se muestra en el siguiente fragmento, las cadenas de documentación no se muestran en la salida, lo que significa que no afecta la salida ni la compilación del código. Las cadenas de documentos se ignoran durante el proceso de compilación.

Conclusión

En esta guía, aprendimos sobre docstrings en NumPy. Comparamos las cadenas de documentación con los comentarios y explicamos la diferencia entre ambos. Aprendimos la sintaxis de docstrings y cómo escribir las docstrings en nuestro código. Además, también tratamos de explicar qué son las cadenas de documentación en NumPy y cómo funcionan con la ayuda de ejemplos. Finalmente, remarcamos que son esenciales para los programadores. No repetiremos la importancia de las cadenas de documentación en NumPy. Solo diremos que debe usar las cadenas de documentación en su código. En NumPy, el estilo de escritura de docstrings es el más popular. Es ampliamente utilizado en la comunidad de programación para informarse mutuamente sobre el funcionamiento y la funcionalidad de sus códigos. Esta guía lo ayudará a comenzar con las cadenas de documentación de NumPy. Intentamos cubrir la mayor parte de lo que necesitará utilizando las cadenas de documentación en NumPy.