Documentación con Doxygen

La documentación es una parte fundamental de la ingeniería de software. En el ámbito académico, documentar el código no solo facilita la legibilidad, sino que también promueve el rigor conceptual al obligar a formalizar las precondiciones, postcondiciones e invariantes del diseño de software.

En la cátedra se utiliza Doxygen para compilar la documentación técnica de las interfaces públicas directamente desde los comentarios del código fuente. Esta guía detalla la configuración y las buenas prácticas para estructurar el código de tus entregas.

1. Instalación de Doxygen y dependencias¶

Para generar la documentación localmente, debés contar con el motor de Doxygen y opcionalmente con Graphviz para renderizar los diagramas de dependencias y llamadas (árboles de ejecución).

# En distribuciones basadas en Debian/Ubuntu (como Ubuntu WSL)
sudo apt-get update
sudo apt-get install -y doxygen graphviz

# En Arch Linux
sudo pacman -S doxygen graphviz

# En macOS (utilizando Homebrew)
brew install doxygen graphviz

2. Configuración mediante el Doxyfile¶

El archivo de configuración principal de Doxygen se llama Doxyfile. Este archivo contiene directivas clave que le indican al motor qué archivos procesar, qué formatos generar (HTML, LaTeX, etc.) y cómo estructurar la salida.

Creación del archivo de configuración inicial¶

Para generar un archivo con las opciones por defecto en la raíz de tu proyecto, ejecutá:

doxygen -g Doxyfile

Configuración recomendada para la cátedra¶

Debés modificar el Doxyfile generado para ajustarlo a las directrices de la cátedra. A continuación se detallan las opciones principales:

Para asegurar la uniformidad en las entregas, podés anexar el siguiente bloque institucional de configuración al final de tu Doxyfile:

# --- Configuración institucional UNRN ---
OUTPUT_LANGUAGE = Spanish
OPTIMIZE_OUTPUT_FOR_C = YES
GENERATE_TREEVIEW = YES
FULL_PATH_NAMES = NO
STRIP_FROM_PATH = include/ src/
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = YES
WARN_IF_UNDOCUMENTED = YES
USE_MDFILE_AS_MAINPAGE = README.md

3. Comentarios del código con notación @¶

En la cátedra se prefiere el uso de la notación @ en lugar del símbolo \ para definir los tags de Doxygen. Los bloques de documentación deben empezar siempre con la firma /** (en C/Java) o ///.

Tags esenciales para funciones y métodos¶

4. Ejemplos de uso práctico¶

Ejemplo 1: Archivo de cabecera en C (punto.h)¶

En C, la documentación de la API pública debe realizarse en el archivo de cabecera .h y no en la implementación .c. Esto permite que el usuario del módulo comprenda la interfaz sin necesidad de inspeccionar el código de bajo nivel.

/**
 * @file punto.h
 * @brief Definición del Tipo de Dato Abstracto (TDA) Punto.
 * @author Cátedra de Programación I
 * @date 2026
 */

#ifndef PUNTO_H
#define PUNTO_H

/**
 * @struct punto_t
 * @brief Representa una coordenada bidimensional en un plano cartesiano.
 */
typedef struct {
    double x; /**< Coordenada en el eje de las abscisas (horizontal). */
    double y; /**< Coordenada en el eje de las ordenadas (vertical). */
} punto_t;

/**
 * @brief Crea un nuevo punto a partir de sus coordenadas cartesianas.
 * 
 * @param x Coordenada en el eje horizontal.
 * @param y Coordenada en el eje vertical.
 * @return punto_t El punto inicializado.
 * 
 * @note Este método no realiza asignaciones de memoria dinámica en la pila
 *       de llamadas principal del sistema.
 */
punto_t punto_crear(double x, double y);

/**
 * @brief Calcula la distancia euclidiana entre dos puntos.
 * 
 * La fórmula implementada es:
 * \f[
 * d = \sqrt{(p_1.x - p_2.x)^2 + (p_1.y - p_2.y)^2}
 * \f]
 * 
 * @param p1 Primer punto de referencia.
 * @param p2 Segundo punto de referencia.
 * @return double La distancia entre ambos puntos expresada en unidades lineales.
 * @warning Si se pasan puntos con coordenadas no inicializadas, el comportamiento
 *          es indefinido.
 */
double punto_distancia(punto_t p1, punto_t p2);

#endif // PUNTO_H

Ejemplo 2: Clase estructurada en Java (Pila.java)¶

En Java, se documentan tanto las clases como sus campos e interfaces públicas mediante comentarios de Javadoc estructurados compatibles con Doxygen.

package ar.edu.unrn.p1.tad;

import java.util.EmptyStackException;

/**
 * Representa una estructura de datos lineal de tipo LIFO (Last In, First Out).
 * Esta implementación no admite elementos nulos.
 *
 * @author Cátedra de Programación I
 * @version 1.1
 * @param <T> Tipo genérico de los elementos almacenados en la pila.
 */
public class Pila<T> {

    private java.util.List<T> elementos;

    /**
     * Constructor por defecto. Inicializa la pila vacía sin elementos preasignados.
     */
    public Pila() {
        this.elementos = new java.util.ArrayList<>();
    }

    /**
     * Inserta un nuevo elemento en el tope de la pila.
     *
     * @param elemento Objeto a apilar.
     * @throws IllegalArgumentException si el elemento provisto es nulo.
     */
    public void apilar(T elemento) {
        if (elemento == null) {
            throw new IllegalArgumentException("No se pueden apilar valores nulos");
        }
        this.elementos.add(elemento);
    }

    /**
     * Desapila y retorna el elemento ubicado en el tope de la pila.
     *
     * @return El elemento desapilado.
     * @throws EmptyStackException si se intenta desapilar de una pila que no contiene elementos.
     */
    public T desapilar() {
        if (this.estaVacia()) {
            throw new EmptyStackException();
        }
        return this.elementos.remove(this.elementos.size() - 1);
    }

    /**
     * Verifica el estado de ocupación de la pila.
     *
     * @return true si la pila no posee elementos, false en caso contrario.
     */
    public boolean estaVacia() {
        return this.elementos.isEmpty();
    }
}

5. Compilación local de la documentación¶

Una vez configurado el Doxyfile y documentados los archivos del proyecto, se puede compilar la documentación localmente utilizando la terminal.

1. Ubicarse en el directorio raíz de la entrega (donde reside el Doxyfile).

2. Ejecutar el comando de compilación:

doxygen Doxyfile

Este proceso analizará el código fuente y creará la carpeta docs/ con las subcarpetas html/ (y latex/ si estuviese habilitada). Para visualizar la página principal interactiva, se debe abrir en el navegador web el archivo:

docs/html/index.html

6. Automatización y despliegue (GitHub Actions)¶

Es altamente recomendable configurar un proceso de integración continua (CI) para compilar y publicar la documentación automáticamente en GitHub Pages tras cada cambio en el repositorio.

Creá el archivo .github/workflows/doxygen.yml con el siguiente contenido:

name: Compilación automática de documentación

on:
  push:
    branches:
      - main
    paths:
      - '**.c'
      - '**.cpp'
      - '**.h'
      - '**.hpp'
      - '**.java'
      - 'Doxyfile'
      - 'README.md'

permissions:
  contents: write

jobs:
  build-docs:
    runs-on: ubuntu-latest

    steps:
      - name: Clonar el repositorio
        uses: actions/checkout@v4

      - name: Instalar Doxygen y Graphviz
        run: |
          sudo apt-get update
          sudo apt-get install -y doxygen graphviz

      - name: Generar documentación técnica
        run: doxygen Doxyfile

      - name: Desplegar en GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/html

7. Diagnóstico y resolución de advertencias comunes¶

Doxygen emitirá advertencias en la terminal si encuentra incoherencias. Mantener la compilación libre de warnings es un requisito para la entrega de proyectos:

• warning: Member xxx (variable) of class yyy is not documented

  • Causa: Tenés habilitado WARN_IF_UNDOCUMENTED = YES y hay un miembro público o privado sin su bloque correspondiente de documentación.

  • Solución: Añadir un bloque breve con @brief o un comentario de línea tipo /**< descripción */.

• warning: parameter 'x' of member yyy is not found in the argument list of ...

  • Causa: El tag @param documenta un parámetro con un nombre que no coincide con el prototipo de la función (suele pasar tras refactorizaciones de código).

  • Solución: Corregir la firma del tag @param para que coincida exactamente con la variable del parámetro en la firma de la función.

• warning: return type of member xxx is not documented

  • Causa: La función retorna un tipo que no es void pero omitiste el tag @return.

  • Solución: Incorporar el bloque @return describiendo el valor retornado.

• warning: Could not open file xxx

  • Causa: La directiva INPUT en el Doxyfile apunta a carpetas o archivos inexistentes.

  • Solución: Ajustar las rutas en INPUT para que coincidan con la jerarquía real de directorios del proyecto.