Doxygen es un generador de documentación pensado originalmente para C++, pero que también funciona con Javascript, PHP y Python, entre otros. A partir de los comentarios del código genera un sitio web navegable con toda la documentación del proyecto: clases, funciones, parámetros y sus relaciones.
Para instalarlo en Ubuntu:
sudo apt-get install doxygen
El primer paso es generar un archivo de configuración en el directorio del proyecto:
doxygen -g Doxyfile
Esto crea un Doxyfile con todas las opciones disponibles y sus valores por defecto. Las
que conviene ajustar para un proyecto, por ejemplo en PHP, son:
EXTRACT_ALL = YES
FILE_PATTERNS = *.php
INPUT = src/
OUTPUT_DIRECTORY = docs/
PROJECT_NAME = "Mi proyecto"
RECURSIVE = YES
Los comentarios en el código usan el formato JavaDoc:
/**
* Calcula el precio final con IVA.
*
* @param float $precio Precio base sin impuestos.
* @param float $iva Porcentaje de IVA (por ejemplo, 18.0).
* @return float Precio con IVA incluido.
*/
function precio_con_iva($precio, $iva) {
return $precio * (1 + $iva / 100);
}
Con el Doxyfile configurado y el código comentado, se genera la documentación:
doxygen Doxyfile
El resultado queda en docs/html/index.html. No requiere servidor web: se puede abrir
directamente en el navegador.
El valor de Doxygen sobre los comentarios en el código es que extrae la estructura completa del proyecto: qué llama a qué, qué hereda de qué, y dónde está cada función. En un proyecto con varias clases y colaboradores, esa visión de conjunto vale más que los comentarios por sí solos.