Regroupement
Doxygen dispose de trois mécanismes pour regrouper des éléments. Un mécanisme fonctionne au niveau global, créant une nouvelle page pour chaque groupe. Ces groupes sont appelés « sujets » dans la documentation. Le deuxième mécanisme fonctionne au sein d'une liste de membres d'une entité composée et est appelé « groupes de membres ». Pour les pages, il existe un troisième mécanisme de regroupement appelé sous-pagination.
Sujets
Le regroupement est un moyen de réunir des éléments sur une page distincte, appelée sujet. Vous pouvez documenter un groupe dans son ensemble, ainsi que tous les membres individuels. Les membres d'un groupe peuvent être des fichiers, des espaces de noms, des classes, des concepts, des modules, des fonctions, des variables, des énumérations, des définitions de type et des définitions, mais aussi d'autres groupes.
Pour définir un groupe, vous devez placer la commande \defgroup dans un bloc de commentaires spécial. Le premier argument de la commande est une étiquette qui doit identifier de manière unique le groupe. Le deuxième argument est le nom ou le titre du groupe tel qu'il doit apparaître dans la documentation.
Vous pouvez faire d'une entité un membre d'un groupe spécifique en plaçant une commande \ingroup dans son bloc de documentation.
Pour éviter de placer des commandes \ingroup dans la documentation pour chaque membre, vous pouvez également regrouper les membres par le marqueur d'ouverture @{ avant le groupe et le marqueur de fermeture @} après le groupe. Les marqueurs peuvent être placés dans la documentation de la définition du groupe ou dans un bloc de documentation séparé.
Les groupes eux-mêmes peuvent également être imbriqués à l'aide de ces marqueurs de regroupement.
Vous obtiendrez un message d'erreur lorsque vous utiliserez le même libellé de groupe plusieurs fois. Si vous ne voulez pas que Doxygen impose des libellés uniques, vous pouvez utiliser \addtogroup au lieu de \defgroup. Il peut être utilisé exactement comme \defgroup, mais lorsque le groupe a déjà été défini, il fusionne silencieusement la documentation existante avec la nouvelle. Le titre du groupe est facultatif pour cette commande, vous pouvez donc utiliser
/** \addtogroup <label>
* @{
*/
...
/** @}*/
pour ajouter des membres supplémentaires à un groupe défini plus en détail ailleurs.
Notez que les entités composées (comme les classes, les fichiers et les espaces de noms) peuvent être placées dans plusieurs groupes, mais les membres (comme les variables, les fonctions, les définitions de type et les énumérations) ne peuvent être membres que d'un seul groupe (cette restriction est en place pour éviter des cibles de liaison ambiguës dans le cas où un membre n'est pas documenté dans le contexte de sa classe, de son espace de noms ou de son fichier, mais uniquement visible en tant que partie d'un groupe).
Doxygen placera les membres dans le groupe dont la définition a la « priorité » la plus élevée : par exemple, un \ingroup explicite remplace une définition de regroupement implicite via @{ @}. Les définitions de regroupement conflictuelles avec la même priorité déclenchent un avertissement, à moins qu'une définition ne concerne un membre sans aucune documentation explicite.
L'exemple suivant place VarInA dans le groupe A et résout silencieusement le conflit pour IntegerVariable en le plaçant dans le groupe IntVariables, car la deuxième instance de IntegerVariable n'est pas documentée :
/**
* \ingroup A
*/
extern int VarInA ;
/**
* \defgroup IntVariables Variables entières globales
* @{
*/
/** une variable entière */
extern int IntegerVariable;
/**@}*/
....
/**
* \defgroup Variables Variables globales
*/
/**@{*/
/** une variable du groupe A */
int VarInA;
int IntegerVariable;
/**@}*/
La commande \ref peut être utilisée pour faire référence à un groupe. Le premier argument de la commande \ref doit être l'étiquette du groupe. Pour utiliser un nom de lien personnalisé, vous pouvez mettre le nom des liens entre guillemets après l'étiquette, comme le montre l'exemple suivant
Il s'agit du "lien" \ref group_label vers ce groupe.
Les priorités des définitions de regroupement sont (du plus élevé au plus bas) : \ingroup, \defgroup, \addtogroup, \weakgroup. La commande\weakgroup est exactement comme \addtogroup avec une priorité inférieure. Il a été ajouté pour permettre des définitions de regroupement « paresseuses » : vous pouvez utiliser des commandes avec une priorité plus élevée dans vos fichiers .h pour définir la hiérarchie et \weakgroup dans les fichiers .c sans avoir à dupliquer exactement la hiérarchie.
Exemple :
/** @defgroup group1 Le premier groupe
* Ceci est le premier groupe
* @{
*/
/** @brief classe C1 dans le groupe 1 */
classe C1 {};
/** @brief classe C2 dans le groupe 1 */
classe C2 {};
/** fonction dans le groupe 1 */
void func() {}
/** @} */ // fin du groupe1
/**
* @defgroup group2 Le deuxième groupe
* Ceci est le deuxième groupe
*/
/** @defgroup group3 Le troisième groupe
* Ceci est le troisième groupe
*/
/** @defgroup group4 Le quatrième groupe
* @ingroup group3
* Le groupe 4 est un sous-groupe du groupe 3
*/
/**
* @ingroup group2
* @brief classe C3 dans le groupe 2
*/
classe C3 {};
/** @ingroup group2
* @brief classe C4 dans le groupe 2
*/
classe C4 {};
/** @ingroup group3
* @brief classe C5 dans @link group3 le troisième groupe@endlink.
*/
classe C5 {};
/** @ingroup group1 groupe2 groupe3 groupe4
* l'espace de noms N1 est dans quatre groupes
* @sa @link group1 Le premier groupe@endlink, groupe2, groupe3, groupe4
*
* Voir aussi @ref mypage2
*/
espace de noms N1 {};
/** @file
* @ingroup group3
* @brief ce fichier dans le groupe 3
*/
/** @defgroup group5 Le cinquième groupe
* Ceci est le cinquième groupe
* @{
*/
/** @page mypage1 Ceci est une section du groupe 5
* Texte de la première section
*/
/** @page mypage2 Ceci est une autre section du groupe 5
* Texte de la deuxième section
*/
/** @} */ // fin du groupe5
/** @addtogroup group1
*
* Plus de documentation pour le premier groupe.
* @{
*/
/** une autre fonction dans le groupe 1 */
void func2() {}
/** encore une autre fonction dans le groupe 1 */
void func3() {}
/** @} */ // fin du groupe1
Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.
Groupes de membres
Si un composé (par exemple une classe ou un fichier) a de nombreux membres, il est souvent souhaitable de les regrouper. Doxygen regroupe déjà automatiquement les éléments par type et niveau de protection, mais vous pensez peut-être que ce n'est pas suffisant ou que ce regroupement par défaut est incorrect. Par exemple, parce que vous pensez que les membres de types (syntaxiques) différents appartiennent au même groupe (sémantique).
Un groupe de membres est défini par un bloc
///@{
...
///@}
ou un bloc
/**@{*/
...
/**@}*/
si vous préférez les commentaires de style C. Notez que les membres du groupe doivent être physiquement à l'intérieur du corps du groupe de membres.
Avant le marqueur d'ouverture d'un bloc, un bloc de commentaires séparé peut être placé. Ce bloc doit contenir la commande @name (ou \name) et est utilisé pour spécifier l'en-tête du groupe. Le bloc de commentaires peut également contenir des informations plus détaillées sur le groupe.
L'imbrication de groupes de membres n'est pas autorisée.
Si tous les membres d'un groupe de membres à l'intérieur d'une classe ont le même type et le même niveau de protection (par exemple, tous sont des membres publics statiques), alors le groupe de membres entier est affiché comme un sous-groupe du groupe de type/niveau de protection (le groupe est affiché comme une sous-section de la section « Membres publics statiques » par exemple). Si deux membres ou plus ont des types différents, alors le groupe est placé au même niveau que les groupes générés automatiquement. Si vous souhaitez forcer tous les groupes de membres d'une classe à être au niveau supérieur, vous devez placer une commande \nosubgrouping dans la documentation de la classe.
Exemple :
/** Une classe. Détails */
class Memgrp_Test
{
public:
///@{
/** Même documentation pour les deux membres. Détails */
void func1InGroup1();
void func2InGroup1();
///@}
/** Fonction sans groupe. Détails. */
void ungroupedFunction();
void func1InGroup2();
protected:
void func2InGroup2();
};
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
/** @name Group2
* Description du groupe 2.
*/
///@{
/** Fonction 2 dans le groupe 2. Détails. */
void Memgrp_Test::func2InGroup2() {}
/** Fonction 1 dans le groupe 2. Détails. */
void Memgrp_Test::func1InGroup2() {}
///@}
/*! \file
* docs pour ce fichier
*/
//!@{
//! une description pour tous les membres de ce groupe
//! (car DISTRIBUTE_GROUP_DOC est OUI dans le fichier de configuration)
#define A 1
#define B 2
void glob_func();
//!@}
Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.
Ici, le groupe 1 est affiché comme une sous-section des « membres publics ». Et le groupe 2 est une section distincte car il contient des membres avec différents niveaux de protection (c'est-à-dire public et protégé).
Sous-pagination
Les informations peuvent être regroupées en pages à l'aide des commandes \page et \mainpage. Normalement, cela donne une liste plate de pages, où la page « principale » est la première de la liste.
Au lieu d'ajouter une structure en utilisant l'approche décrite dans les [sujets]**](#sujets) de la section, il est souvent plus naturel et plus pratique d'ajouter une structure supplémentaire aux pages à l'aide de la commande \mainpage.
Pour une page A, la commande \subpage ajoute un lien vers une autre page B et fait en même temps de la page B une sous-page de A. Cela a pour effet de créer deux groupes GA et GB, où GB fait partie de GA, la page A est placée dans le groupe GA et la page B dans le groupe GB.