Semana 4 Herramietas y Documentacion

La documentación es básicamente enseñar lo que estamos haciendo dentro del programa, le hace saber cómo funciona el código que estamos usando esto hace que las personas que lo vean les resulte fácil de entender nuestro código y tenga una visión de lo que es cada clase, método, atributo entre otras cosas. La documentación hace fácil al lector ver algún error cometido y este lo puede hacer saber al programador. Si se quiere dar mantenimiento al código como ejemplo , la documentación vuelve más sencilla esta parte.
En Python exsisten Docstrings y Pydoc
En Docstrings :
los objetos cuentan con una variable especial __doc__ mediante la que indicar el propósito y uso del objeto. Estos son los llamados docstrings o cadenas de documentación.

A estos atributos se les puede asociar el texto correspondiente explícitamente, asignándolo al literal cadena correspondiente, como con cualquier otra variable. Sin embargo, por conveniencia, Python ofrece un mecanismo mucho más sencillo y es que si el primer estamento de la definición del objeto es una cadena, esta se asocia a la variable __doc__ automáticamente.


view plaincopy to clipboardprint?
01.def haz_algo(arg):
02. """Este es el docstring de la funcion."""
03. print arg
04.
05.print haz_algo.__doc__
06.
07.haz_algo.__doc__ = """Este es un nuevo docstring."""
08.
09.print haz_algo.__doc__

Pydoc

La función help, utiliza el módulo pydoc para generar la documentación de un objeto a partir de su docstring y los docstrings de sus miembros. Este módulo, incluido por defecto con Python desde la versión 2.1, se puede importar en nuestro código Python y utilizarse programaticamente, o bien se puede utilizar como una herramienta de línea de comandos que sería el equivalente a la aplicación Javadoc del mundo Java.

pydoc puede mostrar la información como texto en la consola, tal como lo utiliza help, pero también puede generar archivos HTML como javadoc o facilitar la información a través de un pequeño servidor web incluido con el módulo.