Générer le fichier de base

doxygen -g Doxyfile

Remplir obligatoirement les champs :

• PROJECT_NAME : nom du projet,
• CASE_SENSE_NAMES = NO

Pour une compatibilité avec CMake :

• INPUT = @PROJECT_SOURCE_DIR@/src
• OUTPUT_DIRECTORY = @PROJECT_BINARY_DIR@/doc
• STRIP_FROM_PATH = @PROJECT_SOURCE_DIR@/src
• STRIP_FROM_INC_PATH = @PROJECT_SOURCE_DIR@/src
• EXAMPLE_PATH = @PROJECT_SOURCE_DIR@/tests si existant
• INCLUDE_PATH = @PROJECT_BINARY_DIR@/src @PROJECT_SOURCE_DIR@/src

Pour faire joli :

• TAB_SIZE = 2,
• OPTIMIZE_OUTPUT_FOR_C = NO : si C seulement, pas C++,
• SORT_MEMBER_DOCS = YES,
• SORT_BRIEF_DOCS = YES,
• SORT_MEMBERS_CTORS_1ST = YES,
• SORT_GROUP_NAMES = YES,
• SORT_BY_SCOPE_NAME = YES,
• USE_HTAGS = NO : nécessite global (http://www.gnu.org/software/global/global.html) mais doxygen plante,
• GENERATE_TREEVIEW = YES,
• USE_MATHJAX = YES,
• HAVE_DOT = YES,
• DOT_IMAGE_FORMAT = svg,
• INTERACTIVE_SVG = yes,
• DOT_GRAPH_MAX_NODES = 1000

Pour documentation la plus complète possible :

• ALWAYS_DETAILED_SEC = NO : pas nécessaire,
• INLINE_INHERITED_MEMB = YES : alourdi la documentation mais affiche dans la classe la documentation des membres des parents si héritage il y a,
• TOC_INCLUDE_HEADINGS = 5 : permet d'ajouter les titres des markdown sous forme de liste à puces dépliable dans le sommaire,
• BUILTIN_STL_SUPPORT = YES : complète les diagrammes avec les données de la STL. Ça surcharge beaucoup mais ça permet d'analyser les arguments template des STL.

Sans : Avec :

• EXTRACT_ALL = NO : l'idéal est YES mais à ce moment là, cela désactive les avertissements des membres non documentés,
• EXTRACT_PRIVATE = YES,
• EXTRACT_STATIC = YES,
• EXTRACT_ANON_NSPACES = YES,
• INTERNAL_DOCS = YES,
• SHOW_GROUPED_MEMB_INC = YES : ajoute l'include nécessaire pour chaque membre. A voir…,
• STRICT_PROTO_MATCHING = YES,
• WARN_NO_PARAMDOC = YES,
• FILE_PATTERNS = *.c *.cc *.h *.md : à adapter,
• INCLUDE_FILE_PATTERNS = *.h *.hpp
• RECURSIVE = YES,
• SOURCE_BROWSER = YES,
• REFERENCES_RELATION = YES,
• SKIP_FUNCTION_MACROS = NO,
• CLASS_GRAPH = YES,
• UML_LOOK = NO, si YES, ça fait des diagrammes très gros,
• CALL_GRAPH = YES,
• CALLER_GRAPH = YES.

Dans tous les fichiers qui contiennent de la documentation, il est impératif d'ajouter un @file. Sinon il y a quelques effets pervers : sans @file, un \def de macro ne sera ajouté dans la documentation qu'avec un EXTRACT_ALL..

La documentation s'écrit au maximum dans les fichiers source, pas dans les entêtes.

Avantages : réduction de la taille des entêtes. En cas de modification de la documentation, cela ne modifie pas les entêtes et n'oblige pas la recompilation. Argument final : Qt le fait, c'est un gros projet. On va supposer qu'ils ont étudié la question.

Il va juste rester dans les entêtes la documentation des macros, la description générale des classes et des namespace, les variables non statiques car c'est ce sont les seuls éléments qui ne sont déclarés à aucun moment dans les fichiers sources.

Pour faire référence à un symbole non automatiquement détecté, ajouter un # avant.

Pour mettre en évidence un paramètre, il n'est pas possible de faire un lien. On peut le mettre au format code avec `X`.

Documenter une variable externe avant une fonction interne au fichier. Pour éviter de devoir répéter la définition de la fonction interne, ce qui va permettre à Doxygen de comprendre qu'on change de symbole, il suffit de changer de commentaire Doxygen. Par exemple :

/** \class llgc::math::Hash
 * \brief Class that automatically choose the hash function.
 */
 
/** \brief Compute hash.
 * \param[in] in The string to compute.
 * \return The hash in binary format.
 */
std::vector<uint8_t> llgc::math::Hash::Calc(const std::string& in)