Docstrings, documentando el código
Un docstring es un comentario escrito en la primera instrucción de un módulo, función, clase o definición de método. Internamente se convierte en el atributo __doc__del objeto al que describe.
La función interna de Python help(nombre) proporciona dicha documentación interna. La usaremos siempre que necesitemos ayuda sobre un módulo, clase, método... En todos los temas la usaremos al menos una vez, conviene tener abierta una sesión en la consola interactiva de Python para poder recurrir a esta excelente ayuda.
Escribiendohelp()sin argumentos inicia una sesión interactiva de ayuda, de la que se sale escribiendoquit.
La documentación del código ayuda a sus desarrolladores, y a otros desarrolladores que quieran usar dicho código. En esta asignatura será obligatorio el uso de docstrings en todo el código entregado por los alumnos para ser evaluado.
Se deben usar """triple-comillas-dobles""" alrededor de docstrings. Se debe usar r"""raw-triple-comillas-dobles""" si se va a utilizar la contra-barra (\) en la documentación, y u"""Unicode-triple-comillas-dobles""" si la documentación utiliza códigos Unicode.
Puede ser información muy breve:
"""Esta documentación ocupa sólo una línea"""
O más extensa:
"""Esta documentación es más larga:
Contiene más líneas de información
"""
Se pueden definir diferentes estilos, como se hace en la Guía de Estilo Python de Google:
"""Example Google style docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""