Système de documentation : choix indécidables

Hibou57 · Le 21/03/2011, à 14:16

Hello-hello,

Je me penchais ces derniers temps sur la question d'un système de documentation sur lequel s'arrêter. Ce n'est pas la première fois que je me met face à cette question, je ne l'ai jamais résolu.

Dans le passé, j'ai envisagé des systèmes qui semblaient intéressants, mais qui sont trop peu répandus, et comme je pense qu'on a besoin d'un standard dans le domaine, j'ai fini par les mettre de côté, au registre des curiosités ou des objets d'études.

Donc je me suis restreint à ce qui est assez répandu.

Il faut aussi que ce soit multi-langage, donc bien que PyDoc me plaise bien par la qualité du format HTML qu'il produit, tant par sa capacité a annoter les sources, il est exclu, pour cette raison qu'il ne couvre que Python.

Dans l'idéal, j'aurais aimé un système de documentation qui permet de donner des attributs aux segments du source; ceci, parce que j'ai l'idée d'une extension de ce principe, ou plutôt, d'un usage étendu de ce principe (dont je ne parle ici). Donc JavaDoc aurait put être une option, ou PyDoc, mais encore une fois, ces deux là sont exclus pour la raison donnée plus haut, malgré qu'ils disposent de cette capacité d'annotation/attributs.

Il en existe un, multi-langage, permettant de donner des attributs aux fragments de source, c'est Doxygen. Mais il souffre d'une faible acceptation dans certains milieux, comme le milieux des développeurs Ada. Je pense qu'ils ne l'acceptent pas bien, parce que leur style d'écriture est trop loin de ce qu'exige Doxygen.

J'ai donc envisagé NaturalDocs, qu'ils semblent plus propice a accepter, justement parce qu'il ne repose sur aucun marquage spécifique. Mais comme il ne repose sur aucun marquage spécifique, il ne permet pas de crééer des attributs ou pseudo attributs pour les fragments de sources et de documentations.

Soit, je me suis dit, peut-être serait-il possible d'introduire cette notion d'attribut ou d'annotation, d'une manière qui la rendrait acceptable dans ces milieux, je suppose, sans qu'ils n'aient à écrire le moindre "@" auquel ils semblent définitivement allergiques.

Donc au final, Doxygen et NaturalDocs sont dans la balance.

Seulement un couac arrive : Doxygen ne supporte pas Ada, et NaturalDocs ne supporte pas Python [1]. je me dis donc, qu'il suffit d'en choisir un des deux pour lui ajouter le support du langage manquant, ma préférence allant à étendre NaturalDocs, parce que je le juge plus susceptible d'être accepté.

Je me met donc à la recherche de la licence de NaturalDocs, croisant les doigts pour qu'il ne soit pas sous GPL… Bam! Encore pire que la GPL, il est sous la variante Affero de la GPL. KO.

Soit, je recherche la licence de Doxygen, avec regrets au pensant aux réactions de rejet que provoque ce format de documentation dans certains milieux. Pfff… Docxygen, sous GPL.

Pas la peine, je ne m'investirai pas à faire évoluer aucun des deux.

Donc retour à la case départ, il faut rechercher autre chose. Il faudrait donc que soit ne soit pas sous GPL (cette fois ci je suis obligé d'ajouter ce critère), ou alors qu'il soit qu'il soit sous GPL mais alors qu'il n'ai pas besoin d'être retravaillé et soit utilisable directement en l'état, c'est à dire qu'il supporte tous les principaux langage + Python et Ada et qu'il permettre les annotation ou pseudo attributs dans ajouts de notation spécifique n'ayant pas l'air naturel pour les gens allergiques à ce type de chose.

Des idées ?

[1] NaturalDocs supportent Python d'une bien étrange manière : il ne sait pas prendre en charge les DocStrings de Python, et ne reconnait que les commentaires introduit par "#", si bien qu'il faudrait obligatoirement soit 1) dupliquer tous les DocSstrings dans des commentaires classique, ce qui est évidement exclus, soit 2) retravailler NaturalDocs, ce que à quoi sa licence s'oppose en pratique en le décourageant.

Dernière modification par Hibou57 (Le 21/03/2011, à 14:26)

yohann · Le 21/03/2011, à 15:02

bonjour, je suis peut-être un peu HS, mais je ne vois pas en quoi la licence GPL ou AGPL est décourageante pour retravailler un code source, elle impose simplement que le résultat de ton travail sois soumis à la même licence (c'est a dire GPL ou AGPL), c'est éventuellement un problème si tu compte gagner ta vie en revendant une version modifiée de NaturalDocs qui gère le python car ton premier client aura de facto le droit de consulter et distribuer le logiciel à son tour, mais à part ce cas là je ne vois pas vraiment ce qui est génant.

Hibou57 · Le 21/03/2011, à 15:19

yohann a écrit :

c'est éventuellement un problème si tu compte gagner ta vie en revendant une version modifiée de NaturalDocs qui gère le python car ton premier client aura de facto le droit de consulter et distribuer le logiciel à son tour,

Oui, c'est ça.

Sinon à part ça, je vais quand-même finalement être plus précis sur ce que je disais plus haut, ça aidera peut-être à se faire une image (je pensais ne pas en parler directement).

Quand je parle d'attributs et d'annotations pour en faire un usage étendue, je pense aux vues multiples.

Il y a bien des manières d'avoir des vues multiples : Litterate Programming, Outlining, et la manière des IDE SmallTalk, étant les trois principales. Elles n'ont rien à voir entre elles et ont été introduire indépendamment dans des contexte indépendants, mais elles ont en commun de sortir de la vision linéaire du source d'un programme.

Évidement, l'existence de plusieurs types de vues soulève encore une question de choix. Et justement, pour ne pas se verrouiller sur une seule, autant que pour en permettre plusieurs simultanément, il faut d'abord se pencher sur ce qu'il pourrait y avoir de commun à toutes ces approches. Et ce point commun, c'est d'associer des propriétés à des fragments du source. Début et fin de section pour un IDE comme celui de SmallTalk, ce qui lui permet de les afficher dans différents pan (désolé, je ne connais pas le mot en français), références à des fragments du source pour le Litterate Programming, et enfin, début et fin de section aussi, pour le Outlining [1].

Tout ça n'a pas l'odeur de ce qui est connu, et comme ça n'a pas l'odeur de ce qui est connu, ça provoquerait inévitablement des réactions d'allergies (ce n'est pas qu'une idée que je me fais sans fondement, j'ai déjà tenté d'en parler plusieurs fois sur un Usenet). C'est là qu'est l'intérêt de profiter d'un système de documentation pour introduire ces choses « sournoisement » (une cuillère pour Papa, une cuillère pour Maman… Oh regarde!, elle fait l'avion la cuillère!).

Ça ferait d'une pierre deux coups : système de documentation + sortie de l'archaïque vision texte-linéaire du source d'une programme.

[1] La différence avec le Outlining que tout le monde connait, c'est qu'il est alors défini explicitement, d'une manière comparable à ce que peuvent faire certains modes de Emacs, mais sans être verrouillé à une application spécifique, comme Emacs, justement.

Dernière modification par Hibou57 (Le 21/03/2011, à 15:26)

ehmicky · Le 21/03/2011, à 20:41

Personnellement, j'utilise Doxygen. J'ai pas regardé les autres, donc je peux pas comparer, mais en fait Doxygen me suffit très bien, c'est très rapide et simple de documenter, et facile de personnaliser l'output, et la documentation de Doxygen est bien. Il y a plusieurs bindings mais effectivement la syntaxe de base était prévu pour le C++ je crois, donc peut-être que le binding est mal accepté.
Sinon pour la licence, il me semble que la licence de Doxygen n'a pas de conséquence sur ton travail. La GPL parle de "derived works" mais c'est pour le code source seulement, or Doxygen agit comme un préprocesseur, tu n'inclues donc pas de code de Doxygen dans ton projet, et tu ne lies pas dynamiquement ton projet avec Doxygen. D'ailleurs la syntaxe utilisée dans les balises de commentaires est souvent identique à celle de JavaDoc ou autre. Mais même si c'était pas le cas, la syntaxe /** @param */ n'est pas une propriété intellectuelle de Doxygen. Arrêtez-moi si je dis des bêtises mais je pense que c'est ça.

Hibou57 · Le 21/03/2011, à 22:02

J'imagine qu'il n'y a pas de problème avec le format. Mais ça me prendrait un temps fous de re-créé quelque chose d'équivalent qui reposerait sur le même format. Sinon, pour retravailler l'implémentation actuel de Doxygen qui est sous GPL, ça pourrait aller, mais seulement si c'était pour une retouche rapide. Seulement là, il s'agit d'ajouter un support pour Ada… je ne sais pas si tu connais le langage, mais ça n'a aucune chance de se faire en deux jour, ni même en trois semaine.

Sinon oui, Doxygen m'a l'air intéressant, et surtout il semble extensible (c'est important pour ce que je décrivais plus haut, cette histoire d'attributs ou de métadonnées). La seule chose qui me gène avec lui, c'est que des gens à qui j'en ai parlé sur un Usenet, semblent y être allergiques, ce qui risquerait d'aboutir encore à la situation de 1 langage = 1 système de documentation.

C'est quand-même dommage qu'il n'y ait pas de standard dans ce domaine. Quoique en même temps, quand tu pense à UML, ça peut bien être standard… tu le vois souvent utilisé ? Son adoption ne va pas de soi, et cela depuis toujours. Je sais qu'il n'est pas parfait, mais c'est un standard, et c'est ça qui est important. Mais s'il n'est pas accepté pour la seule raison qu'il repose sur une représentation graphique, ce n'est pas certain alors que quelque chose qui repose sur du texte subirait le même sort.

C'est désespérant, j'ai l'impression depuis des années que rien n'évolue dans ce domaine, ça stagne et ça tourne en rond. Faut dire que les allergies à tout ce qui est « nouveaux » n'y est pas pour rien. Je n'aime pas Java, mais je dois reconnaitre que au moins dans le monde de Java, les choses ont évolué de ce côté là. Je n'en dirais pas autant de certains autres…

Le jour où je tiendrai un moyen de faire accepter l'ajout de ce genre de métadonnées dans les commentaires des sources, je serai content.

Dernière modification par Hibou57 (Le 21/03/2011, à 22:06)

omc · Le 22/03/2011, à 08:53

Beuurkkk, je n'aime pas pourrir les sources avec un tas de balises et d'annotations liées à un système de documentation...

Dernière modification par omc (Le 22/03/2011, à 08:53)

Hibou57 · Le 22/03/2011, à 10:21

omc a écrit :

Beuurkkk, je n'aime pas pourrir les sources avec un tas de balises et d'annotations liées à un système de documentation...

C'est sûr qu'en restant scotché à son modèle d'éditeur de texte brute qui date des années 1950/1960, ça risque pas d'être commode. Déjà pour faire accepter qu'un caractère ce n'est pas un octet ça a été plutôt laborieux [1], j'imagine que pour sortir de ce carcan là, ça va l'être encore longtemps.

Je repasserai plus tard pour une réponse plus complète.

[1] Et encore, l'allergie à Unicode est toujours présente et prête à s'exprimer à la moindre occasion. Par exemple Omc, cela te gêne t-il ou pas de trouver des caractères Unicode dans tes sources ? Ou faut-il qu'il soit strictement plain-ASCII ?

Le Farfadet Spatial · Le 22/03/2011, à 20:36

Salut à tous !

Aujourd'hui, le système le plus utilisé pour la documentation de code semble bien être Doxygen. Si vraiment la GPL te déplait, il faut en créer un tout nouveau. Cela dit, il sera de toute façon toujours difficile de satisfaire aux impératifs de tous les langages présents, passés et futurs : si tu n'en trouves aucun qui corresponde à ton besoin, définie le clairement et ne cherche pas à faire autre chose que de satisfaire ce besoin spécifique – c'est l'un des enseignements d'Unix, un programme ne doit faire qu'une seule chose, mais le faire bien.

De plus, je n'ai pas trouvé dans ton argumentaire quelque chose qui justifie réellement d'exclure la GPL – cela dit, tu as le droit de ne pas l'aimer.

Hibou57 a écrit :

cela te gêne t-il ou pas de trouver des caractères Unicode dans tes sources ? Ou faut-il qu'il soit strictement plain-ASCII ?

De toute façon, quel que soit le langage, les sources en elles-même ne doivent pas utiliser de caractères en dehors de la plage ASCII. Pour les commentaire, il faut utiliser la langue du projet et dès lors, UTF-8 semble aujourd'hui le moyen le plus sûr d'être lisible partout. Toutefois, avec Unicode, j'ai connu des problèmes sous MacOS X (ce qui m'a surpris).

Cela dit, les environnements de travail orientés textes que sont GNU/Emacs et Vim (par exemple) ne datent pas du tout des années 50/60, ne sont pas de simples éditeurs de textes, supportent l'Unicode (ils ont été parmi les premiers à le faire) et encore maintenant, pour qui sait vraiment les utiliser, permettent une productivité supérieure aux environnements intégrés (je dis cela après en avoir testé de nombreux en profondeur).

À bientôt.

Le Farfadet Spatial

Hibou57 · Le 22/03/2011, à 21:16

Hello,

Le Farfadet Spatial a écrit :

De toute façon, quel que soit le langage, les sources en elles-même ne doivent pas utiliser de caractères en dehors de la plage ASCII

Non. Je t'ai déjà parlé d'Ada sur un autre sujet, mais tu ne veux rien entendre. Celui-ci autorise, dans les identificateurs, tous les caractères autorisés comme tel par le standard Unicode. Une variable nommée "π" est légale en Ada.

Le Farfadet Spatial a écrit :

Cela dit, les environnements de travail orientés textes que sont GNU/Emacs et Vim (par exemple) ne datent pas du tout des années 50/60, ne sont pas de simples éditeurs de textes, supportent l'Unicode (ils ont été parmi les premiers à le faire)

Non. Emacs a été l'un des derniers, bien-bien après NotePad sous Windows par exemple

Je passais juste rapidement, je passerai plus tard pour le reste des questions.

omc · Le 23/03/2011, à 15:14

Bonjour,
Faut pas s'énerver, mon intervention, même si elle reflète ma pensée, n'était qu'une boutade.

Hibou57 a écrit :

C'est sûr qu'en restant scotché à son modèle d'éditeur de texte brute qui date des années 1950/1960, ça risque pas d'être commode. Déjà pour faire accepter qu'un caractère ce n'est pas un octet ça a été plutôt laborieux [1], j'imagine que pour sortir de ce carcan là, ça va l'être encore longtemps.
Je repasserai plus tard pour une réponse plus complète.
[1] Et encore, l'allergie à Unicode est toujours présente et prête à s'exprimer à la moindre occasion. Par exemple Omc, cela te gêne t-il ou pas de trouver des caractères Unicode dans tes sources ? Ou faut-il qu'il soit strictement plain-ASCII ?

Puisque tu pousses à la caricature.
Chacun fait ce qu'il veut :
- si tu aimes avoir des balises partout que TOI seul pourra cacher parce-que tu as configuré TON éditeur pour pouvoir le faire.
- si cela ne te dérange pas qu'un tiers ouvre tes sources et voit des Ã© partout où tu as tapé des 'é', des 'è' ou des 'ç'.
- si tu aimes faire du clic-clic plutôt que tu tap-tap.
Libre à toi !

Le Farfadet Spatial · Le 23/03/2011, à 16:58

Salut a tous !

Hibou57 a écrit :

tu ne veux rien entendre

On peut aussi se lancer dans une flaming war, mais ça n'aurait pas d'intérêt.

Celui-ci autorise, dans les identificateurs, tous les caractères autorisés comme tel par le standard Unicode. Une variable nommée "π" est légale en Ada.

Oui, mais il vaut mieux l'éviter, surtout si on veut que le code soit lisible sur de nombreux systèmes : sur des systèmes réputé modernes, j'ai rencontré des problèmes. Il faut voir que le code n'est pas simplement lu par un éditeur de texte, mais par toute une chaîne d'outils. Ce n'est pas une grosse contrainte que de se contenter, dans le code, du pur ASCII – dans les commentaires, on peut envisager d'utiliser un jeu de caractère plus étendu.

Non. Emacs a été l'un des derniers, bien-bien après NotePad sous Windows par exemple

Je ne comprends pas ta remarque. GNU/Emacs est apparu en 1976, Notepad en 1985. Après, pas plus que GNU/Linux, je n'ai pas que Microsoft Windows en tête. De toute façon, il ne s'agit que d'outils, un code ne doit pas être dépendant des outils de développement.

À bientôt.

Le Farfadet Spatial

Ubuntu-fr

Navigation

Liens de recherche

Annonce

#1 Le 21/03/2011, à 14:16

Système de documentation : choix indécidables

#2 Le 21/03/2011, à 15:02

Re : Système de documentation : choix indécidables

#3 Le 21/03/2011, à 15:19

Re : Système de documentation : choix indécidables

#4 Le 21/03/2011, à 20:41

Re : Système de documentation : choix indécidables

#5 Le 21/03/2011, à 22:02

Re : Système de documentation : choix indécidables

#6 Le 22/03/2011, à 08:53

Re : Système de documentation : choix indécidables

#7 Le 22/03/2011, à 10:21

Re : Système de documentation : choix indécidables

#8 Le 22/03/2011, à 20:36

Re : Système de documentation : choix indécidables

#9 Le 22/03/2011, à 21:16

Re : Système de documentation : choix indécidables

#10 Le 23/03/2011, à 15:14

Re : Système de documentation : choix indécidables

#11 Le 23/03/2011, à 16:58

Re : Système de documentation : choix indécidables

Pied de page des forums