Doxygen

C'est un générateur de documentation capable de produire une documentation logicielle à partir du code source d'un programme. Pour cela, il tient compte de la grammaire du language dans lequel est écrit le code source, ainsi que des commentaires.

Le contenu de cette page est valable dans le cadre de la documentation d'un projet en PHP. Pour plus de renseignements, il faut se référer à la documentation officielle.

Définition d'un bloc de documentation

Il y a plusieurs moyen de définir un bloc de documentation. Le plus simple à utiliser avec Netbeans est le JavaDoc :

/**
 *
 */

En effet, il est reconnu par défaut et récupère automatiquement paramètres, valeur de retour et exceptions.

Mots-clefs

Dans la description des commandes décrites, les valeurs entre “<>” sont obligatoires, celles entre “{}” sont optionnelles.
Doxygen reconnait deux syntaxes différentes pour les commandes, celle avec le @ et celle avec le \. Les listes suivantes contiennent un mélange des deux syntaxes car certaines commande commençant par @ sont interprétées par PHPUnit.
Pour la liste complète des mots-clefs, il faut se référer à la documentation officielle.

Description

@author {description} : définition de l'auteur.
\bug {description} : définition des bugs présents dans l'entité.
@deprecated {description} : indication que l'entité est obsolète.
@exception <objet> {description} : définition d'une exception qui peut être générée par l'entité.
@param <type> <nom> {description} : définition d'un ou de plusieurs paramètres de l'entité.
Le type peut être composé si les valeurs sont séparées par des “|”.
Le nom peut être composé si les valeurs sont séparées par des “,”.
@return {description} : définition de la valeur de retour de l'entité.
@see {description} : définition de références pour l'entité.
@since {description} : définition de l'apparition de l'entité. Ça peut être une date, un numéro de version ou tout autre moyen de définir le moment d'apparition de l'entité.
\test {description} : définition des cas de tests de l'entité.
@todo {description} : définition de tâches à faire pour améliorer l'entité.

Mise en forme

\a {mot} : met le mot qui suit en italique.
\b {mot} : met le mot qui suit en gras.
\c {mot} : met le mot qui suit dans une police de type machine à écrire.
\li {description} : permet de générer une liste de valeurs.
\n : force l'insertion d'une nouvelle ligne.
\verbatim : commence un bloc qui affiche le texte tel quel. Les fonctions sont désactivées dans un tel bloc. Le bloc doit se terminer impérativement par \endverbatim.

Configuration

La configuration se fait dans un fichier ini. Il peut être utilisé en ligne de commande ou par l'outil Doxywizard. Il peut être généré manuellement, en ligne de commande ou par l'outil Doxywizard.

ALIASES : ajoute des nouvelles commandes qui seront affichées dans la documentation.
CLASS_DIAGRAMS : insère un diagramme de classe si la valeur est YES.
INPUT : liste de fichiers et répertoires contenant des sources commentées.
JAVADOC_AUTOBRIEF : génère automatiquement la description courte à partir de la première ligne si la valeur est YES. Si la valeur est NO, il faut utiliser la commande \brief.
OUTPUT_DIRECTORY : défini le répertoire de génération de la documentation.
PROJECT_BRIEF : défini une courte description du projet qui apparait sous le nom du projet.
PROJECT_LOGO : défini le chemin d'accès au logo du projet. La taille maximale du logo est 55×200.
PROJECT_NAME : défini le nom du projet.
RECURSIVE : indique si la recherche de documentation se fait de manière récursive ou non.
REPEAT_BRIEF : répète la description courte avant la description détaillée si la valeur est YES.
SOURCE_BROWSER : insère les sources si la valeur est YES. La documentation est automatiquement liée au code et inversement.
STRIP_FROM_PATH : défini la partie du chemin d'accès à ne pas faire apparaître dans la description du fichier source.

Pour la liste complète des options de configuration, il faut se référer à la documentation officielle.

Commandes

Doxygen est destiné à être utilisé en ligne de commande. La génération de documentation peut donc être automatisée.

doxygen -h : affiche la page de manuel.
doxygen [-v] -g [fichier] : génère un modèle de fichier de configuration.
doxygen [-v] -u [fichier] : met à jour un fichier de configuration d'une ancienne version.
doxygen [fichier] : génère la documentation en suivant les règles du fichier de configuration.

Le nom du fichier de configuration peut être omis. Le nom par défaut est Doxyfile.
Le drapeau v indique de ne pas générer de commentaire dans le fichier de configuration.

Examples de fichiers

Avec les deux fichiers ci-dessous, il est possible de générer une documentation basique.

Configuration

Doxyfile

PROJECT_NAME      = "My really special project"
PROJECT_BRIEF     = "So special"
OUTPUT_DIRECTORY  = C:/Test
REPEAT_BRIEF      = NO
STRIP_FROM_PATH   = C:/Test
JAVADOC_AUTOBRIEF = YES
INPUT             = C:/Test
RECURSIVE         = NO
SOURCE_BROWSER    = YES
CLASS_DIAGRAMS    = NO

Source

test.php

<?php
/**
 * The Test class do something.
 * The Test class do something really nice but I wont tell :).
 *
 * @author Me, Myself and I
 * @since version 1.0.0
 * @todo Replace test method by something better.
 */
class Test
{
    /**
     * The test method do something.
     * The test method do something really nice but I wont tell :).
     *
     * @param string  $param1 the first parameter.
     * @param integer $param2 the second parameter.
     * @return a string wich is a concatenation of the inputs
     *
     * @author Me, Myself and I
     * @since version 1.0.0
     * @deprecated since version 2.0.0
     */
    public function test($param1, $param2) {
        $something = $param1 . $param2;
        return $something;
    }
}