Hace algunos años, en un ramo de la universidad, me exigían comentar el código fuente. a medida que comentaba el código me di cuenta que la única utilidad posible de ésto era que otro programados entendiera que hace o como lo hace viendo directamente el código y el comentario, algo muy limitado.
Fue en ese punto cuando conocí la documentación de código fuente, un elemento que lleva los comentarios un paso más allá. Consiste en emplear tags o docstring (dentro de un bloque o línea de comentario) para generar documentos que incluyen entro otros las clases, atributos, métodos, funciones y paquetes.
Python, mediante epydoc podemos emplear varias sintaxis para documentar el código, a continuación les dejo la sintaxis restructuredtext que es la ecolución de epytext. Permite exportar los documentos a html, pdf, latex.
class prueba
'''Esta es una clase de prueba
Las clases de prueba se emplean para ejemplificar alguna cosa.
:ivar algo: Es una variable de la instancia
:type algo: bool
'''
def __init__(self, entrada):
'''Este es el constructor
:param entrada: Es un parámetro de entrada
:type entrada: str
'''
self.algo = entrada
def funcionUno(self):
'''Este método hace algo
:return: Retorna un hola
:rtype: str
'''
return 'hola'
Para generar la documentación debemos ejecutar el siguiente comando:
epydoc path/hasta/fuente -o path/salida/
esto generará la documentación como html, podemos agregar --pdf, --latex, --ps, --dvi para otros formatos.
Actualmente existen herramientas que permiten documentar código en casi cualquier lenguaje.