Se puede documentar una función de Python añadiéndole una cadena de documentación.
Ejemplo 1.4. Definición de la cadena de documentación de la función buildConnectionString
def buildConnectionString(params): """Build a connection string from a dictionary of parameters. Returns string."""
Las tres comillas indican que la cadena ocupa más de una línea. Todo lo que hay entre las comillas es parte de una única cadena, incluidos los retornos de carro y otras comillas. Se puede usar en cualquier punto, pero se ve con más frecuencia al definir una cadena de documentación
 | |
| Las triples comillas son también una forma fácil de definir una cadena que incluya comillas simples y dobles, como qq/.../ en Perl. | |
Todo lo que hay entre las comillas es la cadena de documentación de la función, que explica lo que hace ésta. Una cadena de documentación, si existe, debe ser lo primero que se define en la función (es decir, lo primero que aparece tras los dos puntos). No es técnicamente necesario incluir una cadena de documentación, pero es recomendable hacerlo siempre. Esto lo habrá oído usted en todas sus clases de programación, pero Python añade un incentivo: la cadena de documentación está disponible en tiempo de ejecución como atributo de la función.
| |
| Muchos entornos de programación de Python utilizan la cadena de documentación para proporcionar ayuda sensible al contexto, de modo que cuando se escribe el nombre de una función, su cadena de documentación se muestra como ayuda. Esto puede ser increíblemente útil, pero sólo es tan bueno como lo sean las cadenas de documentación que se escriban. | |
Lecturas complementarias
- La Guía de estilo de Python explica cómo escribir una buena cadena de documentación.
- El Tutorial de Python explica las convenciones de uso del espaciado en las cadenas de documentación.