From: alegrand Date: Tue, 7 Dec 2004 23:52:45 +0000 (+0000) Subject: I will translate one day. However those informations had to be there. X-Git-Tag: v3.3~4789 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/967a54863b79d76e3f6731776c0f2ec319c0ded7?hp=fa2100f09707b904904ddb3bd7b05d07fad350e2 I will translate one day. However those informations had to be there. git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@561 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/README.coding b/README.coding index b4f2b2f697..0b3b6b71bf 100644 --- a/README.coding +++ b/README.coding @@ -103,4 +103,163 @@ PRINTF pointer difference printf ("diff = %ld\n", (long) (pointer2 - pointer1)); - +** +** Commenting the source +** +**************************************************** + +Le format pour cela est : + +/** (très important, la deuxieme étoile) + * nomDeFonction: (faut les deux points) + * @param1: blabla (faut le @ et les deux points, et ca peut + * courir sur plusieurs lignes) + * @param2: blabla + * (fin des paramètres: ligne vide) + * blabla sur la fonction (autant de lignes que tu veux) + */ + +Si tu met () apres un nom de fonction, il essaye d'ajouter un lien +automatiquement, il me semble. + + +Ensuite, quand tu fais "make -C doc", il ne se passe rien de particulier ;) +Avant que ca marche, il faut créer une nouvelle section dans +doc/gras-sections.txt Attention, on dirait du xml, mais le parseur est +stupide. Je me suis arraché les cheveux plusieurs heures pour un " (regarde tbx_log dans le fichier pour +un exemple). + +Une fois la section crée, un "make -C doc" crée un bout de doc, mais ne +l'inclue pas dans la documentation finale. Pour cela, il faut éditer le +fichier gras-docs.sgml (qui est un fichier xml de bon aloi, malgrès son +nom). Il te faut ajouter une entité système dans le prologue (avant "]>") +style: +Ensuite dans le corps du document, tu colles: &tbx-cfg; et t'es arrivé. Au +milleu du gras-docs.sgml, y'a un bout de code mort en commentaire. Autant le +laisser, je nettoyerais un jour, peut etre. + + +Il te faut maintenant mettre un titre long et une description de module. +Pour cela, édite le fichier "tmpl/.sgml". Juste en haut, les +parties "SECTION Title", "SECTION Short_Description", "SECTION +Long_Description" et "SECTION See_Also". Pr les deux premiers, faut mettre +une seule ligne et pas de tags. Pour les autres, il faut faire des +paragraphes. Donc, tout ce que t'as le droit de mettre dans un passe. + +Attention, les fichiers dans doc/xml sont les morceaux prêts à être intégrés +par gras-doc.sgml. Ils sont donc générés et écrasés à tout bout de champ. +Mais les fichiers de doc/tmpl (templates) sont aussi partiellement générés. +Les doc de fonction extraites du code y sont placées, et les modification +que t'y a fait (titre, desc_courte/longue, voir_aussi) sont préservées, +normalement. + + +Voila, une fois ceci fait, la doc devrait être bonne. Comme tu peux le voir, +gtk-doc est bien plus bordelique à utiliser que doxygen (j'utilise souvent +"make clean all" car il semble manquer des dépendances). Mais je préfere car +on peut faire exactement ce qu'on veut. Et pis rose bonbon, c'est plus joli +que bleu triste. + +** +** Using the logs +** +**************************************************** + +Dans gras, tu ne te contente pas d'écrire des choses à l'écran, mais tu +écris sur un sujet particulier (notion de canal) des choses d'une gravité +particulière. Il y a 7 niveaux de gravité. + trace: tracer les entrées dans une fonction, retour de fonction + (famille de macros XBT_IN/XBT_OUT) + debug: pour t'aider à mettre au point le module, potentiellement tres bavard + verbose: quelques infos succintes sur les internals du module + info: niveau normal, ton de la conversation + warning: problème potentiel, mais auquel on a su faire face + error: problème qui t'as empêché de faire ton job + critical: juste avant de mourir + +Quand on compile avec -DNDEBUG (par défaut dans le paquet Debian), tout ce +qui est '>= verbose' est supprimé au moment de la compilation. Retiré du +binaire, killé. + +Ensuite, tu écris dans un canal particulier. Tous les canaux sont rangés en +arbre. Il faudrait faire un ptit script qui fouille les sources à la +recherche des macros XBT_LOG_NEW_* utilisées pour créer des canaux. Le +dernier argument de ces macros est ignoré dans le source. Il est destiné à +être la documentation de la chose en une ligne. En gros, ca fait: +root + +--xbt + | +--config + | +--dict + | | +--dict_cursor + | | +--dict_elm + | | ... + | +--dynar + | +--set + | +--log + | +--module + +--gras + +--datadesc + | +--ddt_cbps + | +--ddt_convert + | +--ddt_exchange + | +--ddt_parse + | +--lexer + +--msg + +--transport + +--raw_trp (Je devrais tuer ce module, un jour) + +--trp_buf + +--trp_sg + +--trp_file + +--trp_tcp + +Et ensuite les utilisateurs peuvent choisir le niveau de gravité qui les +interresse sur tel ou tel sujet. + +Toute la mécanique de logging repose sur des variables statiques dont le nom +dépend du nom du canal. + => attention aux conflits de nom de canal + => il faut une macro XBT_LOG dans chaque fichier où tu fais des logs. + +XBT_LOG_NEW_CATEGORY: nouveau canal sous "root". Rare, donc. +XBT_LOG_NEW_SUBCATEGORY: nouveau canal dont on précise le père. +XBT_LOG_DEFAULT_CATEGORY: indique quel est le canal par défaut dans ce fichier +XBT_LOG_NEW_DEFAULT_CATEGORY: Crèe un canal et l'utilise par défaut +XBT_LOG_NEW_DEFAULT_SUBCATEGORY: devine +XBT_LOG_EXTERNAL_CATEGORY: quand tu veux utiliser par défaut un canal créé + dans un autre fichier. + +Une fois que ton canal est créé, tu l'utilise avec les macros LOG, DEBUG, +VERB, WARN, ERROR et CRITICAL. Il faut que tu donne le nombre d'arguments +après le nom de macro. Exemple: LOG2("My name is %s %s","Martin","Quinson") +Si tu veux préciser explicitement le canal où écrire, ajoute un C devant le +nom de la macro. Exemple: CCRITICAL0(module, "Cannot initialize GRAS") + +Toutes ces macros (enfin, ce en quoi elles se réécrivent) vérifient leurs +arguments comme printf le fait lorsqu'on compile avec gcc. +LOG1("name: %d","toto"); donne un warning, et donc une erreur en mode +mainteneur. + +Enfin, tu peux tester si un canal est ouvert à une priorité donnée (pour +préparer plus de débug, par exemple. Dans le parseur, je fais du pretty +printing sur ce qu'il faut parser dans ce cas). +XBT_LOG_ISENABLED(catName, priority) Le second argument doit être une valeur +de e_xbt_log_priority_t (log.h). Par exemple: xbt_log_priority_verbose + +Voila sur comment mettre des logs dans ton code. N'hesite pas à faire pleins +de canaux différents pour des aspects différents de ton code. En +particulier, dans les dict, j'ai un canal pour l'ajout, le retrait, le +netoyage du code après suppression et ainsi de suite. De cette façon, je +peux choisir qui m'interresse. + + +Pour utiliser les logs, tu déjà faire, non ? Tu colle sur la ligne de +commande un ou plusieurs arguments de la forme + --gras-log=" [+]" (ou sans " si t'as pas d'espace) +chaque réglage étant de la forme: + .thres= +Les différents réglages sont lus de gauche à droite. +"root.thres=debug root.thres=critical" ferme tout, normalement.