Re: [Maitretarot-devel-fr] Documentation

[Yves Mettier]

>> OK, je ne savais pas que cl_game_server generait aussi la doc :)
>>
> Non, il ne genere pas la doc. Et je ne pense pas qu'il le fasse un jour :
> c'est pas son boulot.

Je considere cela comme de la documentation du code.
Pour ceux qui ne connaisent pas ma position sur ce sujet, je suis en grande 
partie
contre documenter son code, parce qu'un code doit etre ecrit de maniere lisible.
En ce qui concerne cardgame_server, on a un cas particulier. Le code contient 
sa propre
documentation et ne peux fonctioner sans ca. Ensuite, on pourrait extraire 
cette doc
avec un outil a part pour generer du docbook. Il etait aussi simple de le coder 
a
l'interieur de cardgame_server.

Donc en ce qui concerne cardgame_server, il y a d'une part la documentation du 
code, et
l'outil qui l'extrait pour generer du sgml. Pour cl_game_server, l'extraction 
de la
documentation, je suis tout a fait d'accord: c'est pas son boulot (idem pour
cardgame_server, et c'est pour ca que j'avais pense a mettre ca dans 
libmaitretarot et
creer cardgame_server pour le serveur, et le generateur de doc a part). Pour la
documentation du code, c'est un choix a faire :)

>
> Par contre la doc que j'avais mis sur le CVS, elle etait a jour (avec ce qui
> est utilise dans cl_game_server). Et je pense qu'elle n'a plus de raison de
> bouger : tout fonctionne impec avec les nouveaux client/ia.

J'avais eu l'impression que c'etait la doc de maitretarot. Dans ce cas: oops, 
mea culpa.
Je vais lire la doc pour recuperer un fichier supprime du CVS (tout l'interet 
du CVS est
la) et le restaurer. A moins que tu ne me devances ?

Par contre, je tiens a un point:
- le module doc ne contient, en termes de protocole, que celui de 
cardgame_server et de
cl_game_server. Il ne doit pas contenir celui de maitretarot_server
- le protocole de maitretarot_server, qui est abandonne, reste bien au chaud la 
ou il
est: dans le repertoire doc du module maitretarot.

> C'est pour ca que je me suis remis a libmt_client : le protocole est robuste
> => on peut l'implementer.

\o/

... et corriger cardgame_server pour qu'il l'applique.

[...]

>> > Je prefere que celui qui veux coder un jeu de bellote developpe son propre 
>> > serveur,
>> > ecrive la doc du protocole qui lui a permis de jouer et en discute avec 
>> > tout le
>> > monde jusqu'a ce que le protocole soit accepte.
>> > Ensuite libre a cardgame_server d'implemente le jeu de belotte ou a 
>> > n'importe qui
>> > d'autre qui veut juste coder un serveur de bellote.
>> >
>> > Et pour ca, il faut que la doc soit independante de toute implementation 
>> > du serveur!
>>
>> On est sur la meme longueur d'onde. Faut juste le faire.
>>
> y a deja le protocole.sgml que j'avais mis dans documentation
> (le chapitre 3 est a jour).

Si je ne me suis pas plante, je l'ai laisse dans guide.sgml.
Par contre, je compte bien le supprimer de guide.sgml pour qu'il apparaisse dans
protocole.sgml.

[...]

>> Dans cardgame_server, il y a des tableaux contenant ce qu'il faut pour 
>> generer la doc.
>> Il est tout a fait possible de modifier ces tableaux sans pour autant 
>> modifier le
>> fonctionnement du serveur. Tant que l'utilisation de ces tableaux n'est pas 
>> faite,
>> rien
>> ne change. Et niveau doc, y'a juste a rajouter des lignes a ces tableaux.
>>
> ah, ok, je n'ai pas ete voir comment etait genere la doc.
> Comment ca ce passe si on veux documente un nouveau jeu ?
> Ce serai bien que ce soit facile d'acces dans un logiciel a
> par.

On y avait reflechi, mais on n'avait pas pousse la reflexion tres loin.
Je refais un nouveau thread avec ce sujet car j'ai pas mal d'experience sur ce 
genre de
choses: mail suivant.

[...]

> Oui, tout a fait! pour l'instant ca me semble plus simple de
> maintenir la doc sous format text puis sgml (meme si ca devient
> lourd a gerer) et si on avait un logiciel qui permet de genere
> automatiquement la doc, je serais preneur (a condition qu'il soit
> indpendant du serveur) :)

...

>> Oui, tout a fait. Sauf pour le format du fichier que je prefere en format 
>> docbook
>> (sgml
>> ou xml) car cela evite de tout refaire ensuite en docbook pour generer du 
>> txt, html,
>> ps
>> ou pdf.
>>
> oui, je trouve aussi que docbook est pratique pour ca.

Un logiciel qui permet de generer automatiquement la doc... Si ca existait, ca 
se
saurait et ferait le bonheur des profs de programmation :)
Mais on a au moins deux sortes d'aides a la generation de doc.

On a des outils comme doxygen. Dans ce cas, il faut documenter enormement, et 
on se
retrouve avec ce que je n'aime pas dans le code: de la documentation redondante 
avec le
code dans l'hypothese ou le code est bien fait. Et cela est de la documentation 
de code.

On a le cas particulier de cardgame_server qui est capable de generer sa propre 
doc a
l'aide de qq fonctions que j'ai faites et qui generent du docbook (sgml) en 
utilisant
les variables memes (des tableaux statiques) de son propre code. Ici, seul
cardgame_server est capable de le faire. On peut tout a fait creer deux 
binaires, l'un
pour le serveur et l'autre pour le generateur de doc. Mais une partie du code 
est
forcement commune.
Et je me demande si je ne vais pas quand meme finalement le faire, histoire 
qu'il n'y
ait pas de code inutile dans cardgame_server. Mais comprenez bien: ce n'est pas 
parce
qu'il y a un generateur de doc utilisant l'implementation du protocole par
cardgame_server que cette doc devient la doc de reference. Elle reste le niveau
d'implementation du protocole par cardgame_server.




Une derniere question...
Il y a dans guide.sgml enormement de commentaires a la fin. Je n'ai pas pris le 
temps de
lire ce que c'etait. Peut-on supprimer, ou au contraire, c'est un brouillon pour
guide.sgml ?

Yves

-- 
- Homepage    - http://ymettier.free.fr - http://www.logicacmg.com -
- GPG key     - http://ymettier.free.fr/gpg.txt                    -
- Maitretarot - http://www.nongnu.org/maitretarot/                 -
- GTKtalog    - http://www.nongnu.org/gtktalog/                    -