octobre
2010
Un article de vinc-mai
Ce quatrième billet présente comment obtenir une documentation grâce à rdoc : il suffit de commenter les fichiers sources.
Documentation
Commenter
Pour documenter les méthodes de la classe TagLib::File, il suffit de commenter les différentes fonctions les implémentant.
La méthode title permet d’obtenir le titre d’une piste. On l’indique en commentaire juste avant la fonction file_get_title.
VALUE
file_get_title(VALUE self)
Par défaut, les paramètres d’une méthode sont nommés p1, p2, …. Pour la méthode title=, on utilise l’instruction call-seq: pour afficher le texte title=title (au lieu de title=(p1)).
call-seq: title=title
Set track title to title
title: a string
*/
VALUE
file_set_title(VALUE self, VALUE title)
La méthode initialize ne devrait jamais être appelée directement depuis un code ruby. On utilise l’instruction :nodoc: pour indiquer que la méthode ne doit pas apparaitre dans la documentation.
VALUE
file_init(VALUE self, VALUE path)
J’indique que je ne désire pas commenter le module TagLib en plaçant un commentaire vide afin d’éviter que rdoc utilise un commentaire non-désiré.
mTagLib=rb_define_module("TagLib");
Dans le fichier lib/raglib2.rb, j’ajoute la directive :main: afin que la page initiale de la documentation pointe sur la classe TagLib::File.
module TagLib
Bizarrement, cette directive ne semble pas fonctionner si elle est placée dans le fichier taglib2.c.
Produire la documentation
Le fichier doc/index.html est créé.
Conclusion
Rendez-vous pour le dernier billet où j’introduirai quelques concepts que je n’ai pas utilisé dans le module TagLib.