Différences

Ci-dessous, les différences entre deux révisions de la page.

--- prog:doxygen [2018/08/23 01:36] – Création root
+++ prog:doxygen [2020/05/11 00:09] (Version actuelle) – Suppression de la taille par défaut pour les images root
@@ Ligne 1: / Ligne 1: @@
-=====La base=====
+=====Création du fichier de base=====
 Générer le fichier de base
   doxygen -g Doxyfile
@@ Ligne 37: / Ligne 37: @@
   * ''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 : {{:prog:doxygen:sans_support_stl.png?200|sans STL}} Avec : {{:prog:doxygen:avec_support_stl.png?200|avec STL}}
+Sans : {{:prog:doxygen:sans_support_stl.png|sans STL}} Avec : {{:prog:doxygen:avec_support_stl.png|avec STL}}
   * ''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'',
@@ Ligne 55: / Ligne 55: @@
   * ''UML_LOOK = NO'', si ''YES'', ça fait des diagrammes très gros,
   * ''CALL_GRAPH = YES'',
-  * ''CALLER_GRAPH = YES'',
+  * ''CALLER_GRAPH = YES''.
+=====Astuces=====
+===@file===
+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.''.
+===Pas de documentation dans les entêtes===
+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.
+===Vrac===
+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 :
+<code>
+/** \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)
+</code>
+^Documentation^Exemple^Commentaire^
+| Namespace | ''\namespace namespace'' |  |
+| Classe | ''\class namespace::Classe'' | Ne pas indiquer les templates mais on peut les ajouter dans la documentation ''\tparam T The class''. |
+| Fonction de classe | ''\fn typefn namespace::classe::function(typeX varX)'' | Le type de retour n'a pas besoin d'avoir le ''namespace''. |
+| Variable de classe | ''\var namespace::classe::variable'' | Pas besoin de mettre le type de la variable. |