⚙️ In-Code Documentation: Doxygen & Sphinx

Principio: “Documentation is a love letter you write to your future self.”

::: info La documentazione “In-Code” consiste nell’estrarre automaticamente manuali tecnici dai commenti presenti nel codice sorgente. Questo approccio garantisce che la documentazione tecnica sia sempre sincronizzata con l’ultima versione del software. :::

1. C++: Lo Standard Doxygen

Doxygen è lo strumento universale per C++. Analizza la struttura del codice e genera siti web (HTML) o documenti (PDF) che mostrano gerarchie di classi e grafi di dipendenza.

Sintassi Javadoc-style (Consigliata)

Utilizziamo i tag standard per descrivere classi, metodi e parametri.

/**
 * @class DataProcessor
 * @brief Gestisce l'elaborazione dei flussi dati in ingresso.
 * 
 * Questa classe implementa il pattern Strategy per elaborare pacchetti
 * provenienti da diverse sorgenti hardware.
 */
class DataProcessor {
public:
    /**
     * @brief Elabora un buffer di dati binari.
     * 
     * @param buffer Puntatore al buffer di input.
     * @param size Dimensione del buffer in byte.
     * @return true se l'elaborazione è andata a buon fine, false altrimenti.
     * @exception std::invalid_argument se il buffer è nullo.
     */
    bool process(const uint8_t* buffer, size_t size);
};

Configurazione (Doxyfile)

Il comportamento di Doxygen è regolato dal file Doxyfile. I parametri critici sono:

• EXTRACT_ALL = YES: Documenta tutto, anche se non ha commenti espliciti.
• HAVE_DOT = YES: Genera diagrammi visuali (richiede Graphviz).
• GENERATE_LATEX = NO: Disabilita la produzione di PDF se non necessaria.

2. Python: Sphinx & Docstrings

Per Python, lo standard è Sphinx. A differenza di Doxygen, Sphinx è estremamente flessibile e permette di integrare manuali narrativi con la documentazione automatica del codice.

Google Style Docstrings

È il formato più leggibile e moderno. Richiede l’estensione napoleon in Sphinx.

def calculate_metrics(data: list[float], threshold: float = 0.5) -> dict:
    """
    Calcola le metriche di performance basate su una soglia.

    Args:
        data (list[float]): Lista dei valori grezzi da analizzare.
        threshold (float): Valore di soglia per la classificazione. 
            Defaults to 0.5.

    Returns:
        dict: Un dizionario contenente 'mean', 'variance' e 'hit_rate'.

    Raises:
        ValueError: Se la lista data è vuota.
    """
    if not data:
        raise ValueError("Input data cannot be empty.")
    # Implementation...
    return {"mean": 0.0, "variance": 0.0, "hit_rate": 0.0}

Estensione autodoc

Sphinx utilizza la direttiva autodoc per importare i moduli Python e leggere le docstring:

.. automodule:: my_project.processor
   :members:
   :undoc-members:
   :show-inheritance:

📉 Workflow di Estrazione (Mermaid)

graph TD
    SRC[Source Code: .cpp / .py] -->|Parser| TOOL{Doc Tool}
    TOOL -- Doxygen --> HTML_CPP[HTML Reference C++]
    TOOL -- Sphinx --> HTML_PY[Static Site Python]
    
    HTML_CPP --> WIKI[Wiki integration / Web Server]
    HTML_PY --> WIKI
    
    style TOOL fill:#f9f,stroke:#333,stroke-width:2px

💡 Engineering Tips per Documentazione di Qualità

1. Non documentare l’ovvio: Inutile scrivere @param x Il parametro x. Spiega invece il ruolo o le unità di misura (es. @param timeout_ms Timeout in millisecondi).
2. Usa i Type Hints: In Python, usa sempre i Type Hinting. Sphinx li rileverà automaticamente, rendendo la documentazione più precisa senza sforzo aggiuntivo.
3. Cross-Reference: Usa i link tra classi. In Doxygen basta citare il nome della classe per creare un link ipertestuale automatico.
4. Esempi d’uso: Includi sempre uno snippet di esempio (tag @code in Doxygen o blocchi code-block in Sphinx).

Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #Doxygen #Sphinx #Python #CPP #AutoDocs