[Toulibre] Doxygen en 2022

[Lcaracol]

Le Mon, 19 Dec 2022 22:35:52 +0100,
Sébastien Dinot via Toulouse-ll <toulouse-ll at toulibre.org> a écrit :

> 
> Ton analyse est intéressante et confirme malheureusement ce que je
> subodorais :
> 
> « [...] vu le caractère exceptionnel de la chose, je me dis que la
> mise en œuvre de cette fonction ou l’écriture des pages ne doivent
> pas être une sinécure »
> 
> :)
> 

Ça je sais pas trop, je suppose que pour quelqu'un qui connaît déjà
Doxygen ce doit pas être si terrible. Mais le fait qu'ils aient rajouté
la possibilité de faire des pages en markdown, en rajoutant juste
quelques commandes spécifiques à Doxygen, c'est pas négligeable. Ils
doivent prévoir de faire venir de nouveau utilisateurs, qui
connaîtraient et seraient déjà habitués à Markdown

MkDocs aussi utilise markdown.


>   Manque de chance, le dépôt Github du projet doxybook2 vient d'être
>   archivé par son auteur :
> 
>   https://github.com/matusnovak/doxybook2
> 
>   Autrement dit, tant que quelqu'un n'en reprendra pas durablement la
>   maintenance, ce n'est pas le cheval sur lequel miser.
> 

Dans Kaamelott le chevalier au Lion a dit, à propos de la
chevalerie, qu'on peut douter de beaucoup de choses, sauf de la
nécessité de se mettre toujours du côté de celui qui a le pognon.

Donc il semble avisé d'essayer de savoir sur quel cheval misent les
boîtes du complexe militaro-industriel yankee. Parce que s'ils ont
besoin de maintenance, ils trouveront le pognon pour que le projet
continue à vivre. Le pognon c'est eux qui le font.

>
> Malgré ses divers défauts, Doxygen a longtemps été incontournable pour
> documenter les logiciels en C++. Je l'ai aussi utilisé à plusieurs
> reprise pour effectuer du reverse engineering sur du code que je
> découvrais et que je devais analyser ou faire évoluer. Les graphes
> d'héritage et de collaboration que génère Doxygen sont précieux dans
> ces moments-là.

J'ai déjà entendu des developpeurs expérimentés en C m'expliquer
qu'ils utilisaient Doxygen avec ses paramètres par défaut juste pour
ces graphes. Quand ils tombent sur un nouveau projet ça leur permet de
se faire une idée en ayant une vision d'ensemble.

Et je remarque aussi qu'entre le projet m.css , le projet doxybook, et
le trio Doxygen + Breathe + Sphinx, il y a pas mal de systèmes qui
continuent d'utiliser Doxygen en coulisse.

Et ce que j'en conclu, c'est que quoi qu'il arrive il reste pertinent
d'écrire les commentaires en gardant la syntaxe de Doxygen, puisque
pour parser les fichiers sources ce sera toujours Doxygen qui sera
utilisé.

> 
> Au détour de mes recherches, je suis tombé sur un thème pour Doxygen
> bien plus sympa que le thème originel :
> 
> https://mcss.mosra.cz/documentation/doxygen/
> 
> Et pour le coup, l'auteur de ce thème utilise les fonctions avancées
> de Doxygen pour produire une documentation complète de logiciel :
> 
> https://doc.magnum.graphics/magnum/
> 
> Belle performance vu ce que tu m'as dit sur la mise en œuvre de ces
> fonctions dans Doxygen !
> 

Je suis très très loin d'être une référence pour parler de Doxygen.
Beaucoup de gens auront ici beaucoup plus d'expérience que moi dans son
utilisation, et en parleront sûrement mieux. Donc je vais pas trop
m'avancer sur la mise en oeuvre de fonctions dans Doxygen. Avant ta
réponse je savais même pas quelle était l'importance réelle que Doxygen
avait pu avoir. J'ai juste été surpris le jour où j'ai compris que la
doc de l'avr-libc était faite avec, parce qu'elle avait pas le même
aspect bleu typique que toutes les autres.

Mais je remarque moi aussi que en partant de Doxygen et en rajoutant ce
thème m.css, il est possible de faire quelque chose de moderne. Donc il
y a encore des gens qui l'utilisent, et surtout qui savent bien
l'utiliser, pour en faire quelque chose de moins austère que ce que
donnent les réglages par défaut.

Tout ça me donne l'impression que aujourd'hui encore Doxygen n'est pas
tout à fait désuet. Et j'ai par contre du mal à comprendre quels sont
ses remplaçants qui génèrent un site à partir des commentaires, hormis
Sphinx.

Je suis tombé aussi sur une utilisation de Doxygen pour Dolibarr, donc
pour du PHP:
https://jtraulle.github.io/dolibarr/index.html  

Et là encore ils utilisent toujours les mêmes paramètres par défaut avec
le même dégradé de bleu caractéristique que ce qu'il y avait pour rpm
et les autres. Mais ce n'est pas ce qu'il y a dans la doc officielle.
Sur leur site ils utilisent un wiki:
https://wiki.dolibarr.org/index.php?title=Developer_documentation

-------------- section suivante --------------
Une pièce jointe autre que texte a été nettoyée...
Nom: non disponible
Type: application/pgp-signature
Taille: 801 octets
Desc: Signature digitale OpenPGP
URL: <http://toulibre.org/pipermail/toulouse-ll/attachments/20221220/a7442dbf/attachment.sig>