Re: [Maitretarot-devel-fr] Documentation

[Philippe Brochard]

"Yves Mettier" <address@hidden> writes:

> >> 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 :)
> 
Oui, pour la doc du code, je suis du meme avis que toi : il vaut
mieux faire un code bien lisible (nom de fonction explicite) plutot
que des commentaires toutes les 2 lignes.

> >
> > 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 ?
> 
bon, je regarde si tu l'as remis sur le CVS, sinon j'en ai une
copie en local => je le remet sur le CVS (tu me le vire pas
cette fois ci :))

> 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.
> 
oui, le protocole obsolete doit rester sur le CVS mais pas etre trop
apparent pour qu'on ni fasse plus reference.

> > 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.
> 
Bon, ben je met protocole.sgml avec seulement le chapitre 3
qui est a jour (si tu ne l'as pas deja fais).

> [...]
> 
> >> 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.
> 
ok : vu


[...]


> >> 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.
> 
j'ai pas trop apprecier doxygen : je trouve le formatage des
commentaire assez lourd.

Je prefererai un logiciel qui parse le code (regarde directement
les definitions des fonctions) et ensuite genere un fichier html
a partir de ça : reste plus qu'a rajouter les commentaires s'il 
y a lieu.

> 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.
> 
ok, c'est tres clair comme ca :)

> 
> 
> 
> 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 ?
> 
j'avais laisse ces commentaire au cas ou il aurai fallut revenir
en arriere, mais le CVS est la pour ca => on peut les virer.


Philippe

-- 
Philippe Brochard    <address@hidden>
                      http://hocwp.free.fr

-=-= http://www.gnu.org/home.fr.html =-=-