[Toulibre] Doxygen en 2022

[Sébastien Dinot]

Lcaracol via Toulouse-ll a écrit :
> Ça je sais pas trop, je suppose que pour quelqu'un qui connaît déjà
> Doxygen ce doit pas être si terrible.

Ce qui est terrible, c'est d'avoir un outil qui, pour arriver à produire
tout ce qu'il doit produire, exploite plusieurs syntaxes. C'est ce qui
a tué les autotools.

> MkDocs aussi utilise markdown.

Je n'ai rien contre Markdown que j'utilise au quotidien. Ceci étant,
s'il est un peu plus compliqué, le format reStructuredText sur lequel se
base Sphinx, est plus indiqué pour écrire des documents complexes (il
manque pas mal de choses au Markdown originel et ce n'est pas un hasard
s'il existe une dizaine de déclinaisons de ce format).

> Donc il semble avisé d'essayer de savoir sur quel cheval misent les
> boîtes du complexe militaro-industriel yankee. [...]

Ce genre d'argument défoule sans doute, mais il n'apporte rien au débat,
d'autant plus que le libre a montré depuis longtemps qu'il n'attendait
pas les financements du complexe militaro-industriel américain, chinois,
français, russe, allemand, israélien, italien, suédois ou suisse pour
exister.

> 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.

Tout à fait, parce que, comme je l'indiquais, développer un outil de
documentation d'API ne se fait pas en un soir sur un coin de table,
surtout lorsqu'on adresse un langage aussi complexe que le C++ et encore
plus si l'on tient à générer des diagrammes UML.

Si on veut conserver le périmètre fonctionnel de Doxygen et l'étendre,
il semble donc plus judicieux d'exploiter cet outil et d'intégrer les
fichiers qu'il produit dans un sur-ensemble.

Mais on peut aussi vouloir se débarrasser de Doxygen, quitte à perdre
(temporairement ?) sur le plan fonctionnel, en écrivant un outil neuf
qui embrasse plus largement le problème de la documentation de code.
C'est le pari de hdoc (dont les commentaires qui documentent l'API
reprennent partiellement la syntaxe de Doxygen, mais sont traités par
hdoc, et non par Doxygen).

> 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é.

Non, pas toujours.

> 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.

hdoc.

Pendant longtemps, il a été compliqué d'écrire un outil documentant du
code C++ car le code C++ est complexe à analyser. Aujourd'hui, LLVM et
Clang fournissent tous les outils nécessaires pour cela et bien d'autres
choses (par exemple, la validation syntaxique du code dans l'éditeur) et
cela ouvre la voie à de nouveaux projets, tel que Standardese :

https://standardese.github.io/

(je n'en ai pas parlé jusque-là parce que le projet semble être en train
de s'essouffler).

Mais je te rassure, vu la base installée, Doxygen ne mourra qu'avec le
C++.

Sébastien


-- 
Sébastien Dinot, sdinot at april.org
April, http://www.april.org/
Promouvoir et défendre le logiciel libre