Documentadores

De Departamento de Informatica
Saltar a: navegación, buscar

Contenido

Introducción

Uno de los mayores problemas de un programador es leer código ajeno, usualmente la dificultad de comprensión del codigo es directamente proporcional al tamaño de éste. Comprender la organización del código es tedioso incluso cuando este esta bien comentado, ya que se debe viajar por miles y miles de lineas de código. Incluso cuando el proyecto no es un programa sino una biblioteca que queremos usar, tenemos que pasar largas y tediosas horas leyendo código e intentando entender el porqué de cada archivo de cabecera, de cada archivo fuente, de cada función... cuando en realidad no queremos saber como está implementado sino como usar la biblioteca.

Es por esto que es importante tener un buen documentador, ya que este ahorra la tediosa tarea de tener que crear un documento, generando éste automáticamente. A continuación se explicarán algunos documentadores útiles durante la programación de distintos proyectos.

Doxygen

Doxygen es una herramienta para generar documentación a partir del código fuente. Es un sistema de documentación para C++, C, Java, ObjectiveC, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#.

Para hacer uso de todas las características de Doxygen, se deberá instalar también las siguientes herramientas:

  • Una distribución de LATEX en caso de querer generar un documentador con formato PDF.
  • Graphviz o Graph visualization toolkit en caso de querer incluir gráficos.
  • Python para genera la documentación propia de doxygen.

Compilación

  • gunzip doxygen$VERSION.src.tar.gz descomprime el archivo.
  • tar xf doxygen$VERSION.src.tar desempaqueta el archivo.
  • ejecute el script configure: sh ./configure

Compile el programa ejecutando: make

El programa debería compilar sin problemas y tres binarios deberían crearse en el directorio bin de la distribución. Luego de compilar las fuentes ejecute un make install para instalar doxygen.

Generando la documentación

  • Primero, generamos un archivo de configuración:
doxygen g "configfile"  Donde configfile es el archivo de configuración.

Este archivo es similar a un makefile. No tendremos problemas a la hora de entender las opciones ya que hay multitud de comentarios. las lineas a cambiar son:

  • linea 28: El nombre del proyecto (Por ejemplo PROJECT_NAME = "Mi proyecto")
  • linea 34: La versión (PROJECT_NUMBER = 0.1)
  • linea 41: Directorio de salida (OUTPUT_DIRECTORY = ./doc)
  • linea 63: El idioma (OUTPUT_LANGUAGE = Spanish)
  • linea 584: Los ficheros de entrada (INPUT = ./include/header.h ./src/main.py)
  • linea 700: Si queremos poder navegar por el código (SOURCE_BROWSER = YES)
  • linea 777: Si queremos generar la documentación HTML (GENERATE_HTML = YES por defecto)
  • linea 1088: Si queremos generar la documentación LaTeX (GENERATE_LATEX = YES por defecto)

Para mayor detalle, revise los comentarios dentro del mismo archivo de configuración generado en su proyecto. Una vez lista la configuración ingresamos el comando:

 doxygen  

Lo que nos creará la documentación en el formato especificado. Si hemos indicado que genere documentación HTML (por defecto) generará, entre otros, un archivo index.html en la carpeta HTML que podremos abrir con un navegador. En caso de haber establecido en la configuración mas tipos de datos de salida, se generara una carpeta por cada uno de ellos con un archivo dentro el cual posee la documentación del codigo de forma ordenada.

Ejemplo de documentación

## @package pyexample
   2 #  Documentation for this module.
   3 #
   4 #  More details.
   5 
   6 ## Documentation for a function.
   7 #
   8 #  More details.
   9 def func():
  10     pass
  11 
  12 ## Documentation for a class.
  13 #
  14 #  More details.
  15 class PyClass:
  16    
  17     ## The constructor.
  18     def __init__(self):
  19         self._memVar = 0;
  20    
  21     ## Documentation for a method.
  22     #  @param self The object pointer.
  23     def PyMethod(self):
  24         pass
  25      
  26     ## A class variable.
  27     classVar = 0;
  28 
  29     ## @var _memVar
  30     #  a member variable 

Lo cual genera el siguiente archivo de documentación que puede visualizar haciendo click Aquí

Rdoc

Docco

GoDoc

Referencias

Herramientas personales
Espacios de nombres
Variantes
Acciones
Navegación
Herramientas