Dans ce chapitre, nous utiliserons la console pour créer une documentation, ce qui est quand même plus efficace que si nous le faisions manuellement.
Principe de fonctionnement
Vous souhaitez que n’importe qui puisse comprendre le fonctionnement de votre programme, de vos classes, méthodes, etc. ? La meilleure solution est de créer une documentation. C'est-à-dire un ensemble de fichiers HTML, pouvant être consultés en ligne ou non, détaillant le fonctionnement de votre code. Pour cela, il faut que vous commentiez votre code (en français et/ou anglais si possible).
Assurez-vous que rdoc est installé sur votre machine (pour Windows : il est présent dans l'installateur, pour Linux : dans les dépôts).
Lorsque vous exécutez rdoc, vous pouvez lui passer la liste des fichiers à documenter :
rdoc [fichier1] [fichier2] [etc.]
Si vous ne lui en passez aucun, il génère la documentation pour tous les fichiers du répertoire courant.
Cela a eu pour conséquence de créer un dossier /doc/ dans votre répertoire, qui contient vos fichiers HTML dont l'architecture est la suivante : les fichiers, classes et méthodes sont listés en haut, le détail du code apparaît au centre (avec vos commentaires).
Les commentaires peuvent s'appliquer à ce que vous voulez : une classe en général, mais pourquoi pas à une méthode particulière. Vous pouvez créer une documentation pour ce code et voir par vous-mêmes les différents emplacements possibles pour les commentaires :
# classe Chanteur
class Chanteur
def initialize(nom)
# initialise l'instance de la classe Chanteur
@nom = nom
end
def chante(chanson)
# définit la méthode chante de la classe Chanteur
@chanson = chanson
end
end
Mettre en forme la documentation
Il existe différents moyens d'améliorer la lisibilité des pages.
Modifier la typographie
Il vous est par exemple possible de modifier la typographie à certains endroits du texte : mettre des parties en gras, en italique ou d’utiliser une police à taille fixe (l'équivalent de la balise <pre> en HTML).
La procédure n’est pas la même pour les groupes de mots que pour les mots isolés, voici comment procéder :
Pour des mots isolés
# je souhaite mettre ce mot en _italique_
# celui-ci en *gras*
# et pourquoi pas ne pas utiliser une +police_fixe+ ?
Pour des groupes de mots
# <i>ces mots seront en italique</i>
# <b>ceux-ci en gras</b>
# <code>et ces derniers à police fixe</code>
Hiérarchiser la documentation
Afin de mieux hiérarchiser votre document, il est également possible de placer des titres et des sous-titres.
6 niveaux existent, les titres les plus importants sont précédés d'un =, les moins importants de ======.
Cette hiérarchie suit le même ordre que celle établie en HTML (de <h1> à <h6>) :
# = Le titre le plus important
# == Un sous-titre un peu moins important
# === Un autre sous-titre de moindre importance
# ==== Encore moins important
# ===== Toujours moins important
# ====== Un titre (presque) sans importance
Créer des listes
Vous pouvez placer des listes au sein de votre code. En voici quelques exemples.
Listes à puces
# * premier objet listé
# * second objet listé
Listes ordonnées
# 1. premier objet énuméré
# 2. second objet énuméré
Listes de définition
# [premier objet à définir] première définition
# [second objet à définir] seconde définition
Tableaux
# première colonne, première ligne :: seconde colonne, première ligne
# première colonne, seconde ligne :: seconde colonne, seconde ligne
Sachez également qu’à l'intérieur de la documentation, à chaque fois que vous mentionnez une classe, un fichier ou une méthode, cette référence devient un lien pointant vers cette destination. De plus, les URL sont automatiquement converties en lien.
Si vous voulez qu'une classe ou une méthode ne soit pas documentée, c’est très simple, il vous faut la commenter de cette manière :
class ClassCachee # :nodoc:
end
def MethodeCachee # :nodoc:
end
Ainsi, le code en question ne sera pas répertorié dans la documentation.