Documenter un package avec inlinedocs

Le package R inlinedocs permet de générer la documentation d'un package (c'est-à-dire les fichiers Rd contenant l'aide en ligne des fonctions du package) à partir de commentaires inclus dans le source R. Contrairement à ROxygen, ces commentaires peuvent être situés n'importe où dans le source, notamment à proximité du code qu'ils commentent.

 

Sommaire

 

Version testée inlinedocs 1.5

Le principe

  • On rappelle tout d'abord, que, selon les conventions de R, le fichier documentant une fonction ou classe R de nom "myfun" doit être nommé "myfun.Rd" et être situé dans le répertoire nommé man. Il doit respecter le format Rd (voir la documentation du format Rd) et être structuré en sections de noms prédéfinis. Pour une fonction, ce sont Description, Usage, Arguments, Value, Details, References, Author, Examples, etc .... Certaines sections sont obligatoires.
  • inlinedocs construit automatiquement le fichier "myfun.Rd" à partir de commentaires inclus dans le source R de la fonction "myfun".

Syntaxe des commentaires reconnus par inlinedocs dans le cas d'une fonction

  • Les commentaires reconnus par inlinedocs sont ceux précédés de:
    1. 1.
      ###
      dans le cas où
      • - placés sur les lignes qui suivent "function(", ils correspondent au paragraphe "Description" de la documentation et décrivent les fonctionnalités de la fonction,
      • - placés sur les lignes qui suivent le nom d'un argument de la fonction, ils décrivent celui-ci,
      • - placés avant l'accolade qui ferme le corps de la fonction, ils correspondent au paragraphe "Value" de la documentation et décrivent la valeur retournée par la fonction.
    2. 2.
      ##<<
      dans le cas où, placés après le nom d'un argument et sur la même ligne, ils décrivent celui-ci. Si la ligne ne suffit pas à décrire l'argument, les lignes suite doivent être précédées par 2 dièzes.
    3. 3.
      ##section<<
      section étant le nom d'une section  parmi: alias, author, description, details, keyword, note, references, seealso, title, value. Les commentaires qui suivent cette balise correspondent alors au contenu de la section. Les lignes suite doivent être précédées par 2 dièzes. Plusieurs balises concernant la même section peuvent apparaître dans le source de la fonction: les commentaires seront mis à la suite les uns des autres.
      Attention: Si aucune section author ne figure, la section Author est génére automatiquement à partir de la clause Author du fichier DESCRIPTION.
  • Les commentaires introduits par un seul dièze ou plus de 3 dièzes sont ignorés de inlinedocs.
  • Les marques de mise en page reconnues dans le format Rd (celles introduites par un "\", par exemple \cr pour un retour à la ligne; voir la documentation du format Rd), sont laissées telles quelles à l'intérieur des commentaires inlinedocs et donc seront interprétées lors de la mise en page du fichier.

La construction et la visualisation des fichiers d'aide

  • La génération des fichiers .Rd se fait par la commande R package.skeleton.dx.
    1. 1. Se placer dans le répertoire au-dessus de celui qui contient le package. Par exemple, soit un package de nom MYPKG. Selon les conventions de R, il est situé dans un répertoire de même nom, par exemple /home/moi/MYPKG. On se place dans /home/moi.
    2. 2. Ouvrir une session R et taper:
      install.packages("inlinedocs",repos="http://r-forge.r-project.org") # si le package inlinedocs n'est pas encore installé
      library(inlinedocs)
      package.skeleton.dx("MYPKG")
    Dans le répertoire /home/moi/MYPKG/man, tous les fichiers Rd correspondant aux fonctions R qui contiennent des commentaires inlinedocs sont alors crées ou remplacés. Un fichier MYPKG-package.Rd est également créé à partir du fichier DESCRIPTION.
  • On peut exclure du precessus les fonctions dont le nom satisfait une expression régulière en utilisant l'argument excludePattern. Exemple:
    package.skeleton.dx("MYPKG", excludePattern="my.*")
    
  • Si on veut visualiser le "rendu" de ces fichiers, il est nécessaire de les convertir dans un autre format en utilisant la commande R CMD Rdconv. Par exemple, pour visualiser le rendu du fichier myfun.Rd
    cd /home/moi/MYPKG/man # se placer dans le répertoire qui contient les fichiers Rd
     R CMD Rdconv -t html myfun.Rd -o /tmp/myfun.html
    
    Ouvrir /tmp/myfun.html dans un navigateur.

Exemple d'un fichier source commenté avec des balises inlinedocs


Cet exemple, tout-à-fait fictif, est inspiré de celui fourni dans la documentation de inlinedocs. Il peut sembler compliqué a priori, mais il illustre presque toutes les possibilités de inlinedocs, plus quelques-unes du langage Rd, les balises Rd étant introduites par un "\"
myfun <- function(
     ### This function does nothing but does it very well. 
     ### For example with LaTeX mathematical formula:     
     ### \eqn{\alpha=\beta} and                              
     ### \deqn{p(x)=\frac{\lambda^x e^{-\lambda}}{x!}}{p(x)=lambda^x exp(-lambda)/x!}
     ### for \eqn{x=0,1,2, \ldots}.
                          first         
		### the first argument is blabla
	,second
		### the second argument is blabla
	,third 	##<< the third argument is described on this line 
	,fourth=      ##<<  the fourth argument has a default value of type list.
		## Here is the description of each of the components
		##describe<<
		list(this="that",           ##<< the component \code{this} contains  blabla
	        	that="other",       ##<< the component \code{that} contains  blabla
			foo="bar") # (composant non décrit)
		##end<<
	){
       	##details<<
	## if second is TRUE then the sum of \code{first} is calculated
# Personal comment:  second is a logical     
	if ( second ){
		res <- sum(first)
	} else {
		##details<<   
		## if second is not TRUE then a list is created
		##describe<< The contents of the list are:
                 res <- list(x=7, ##<< \code{x} coordinate
	        	z= ##<< \code{z} is itself a list, with components:
				##describe<<
				list(colour=green, ##<< colour of line
					width=2),     ##<< width of line
			##end<<
			## and this line ends documentation for z
			y=10)##<< \code{y} coordinate
	}
	##note<< we have to notice that
        ## patati patata
	##references<< See me and  al. 2010 
        ## \url{http://hal.archives-ouvertes.fr/blabla/fr/}
	##seealso<< \code{\link{test}}    
  ### A scalar or a list is returned, see Details   
}
La construction du fichier Rd:
cd /home/moi
R
< library(inlinedocs)
< package.skeleton.dx("MYPKG")
La conversion du fichier genéré en format html
cd /home/moi/MYPKG/man 
R CMD Rdconv -t html myfun.Rd -o /tmp/myfun.html
La visualisation du fichier format html
firefox /tmp/myfun.html

Le paragraphe Example

Le paragraphe "Example" des helps peut être décrit,
  • soit dans un attribut nommé ex que l'on rajoute à la fonction à documenter. Celle-ci doit alors déclarée selon le modèle:
    myfun <- structure(function(...) { ...}, ex=function() {les commandes R de l'exemple})
  • soit dans un fichier du même nom que la fonction à documenter placé dans le répertoire tests

Documenter une classe S4

Exemple:
setClass("TunLasso", # TunLasso-class
         ### The TunLasso class represents the output of \code{\link{EstimTunLasso}}
         ##details<< Objects can be created by calls to the function \code{\link{EstimTunLasso}}
         representation(f="matrix" ##<< matrix \code{n x Nmod}. \code{n} is the number of observations. 
                        ))
  • Le commentaire "# TunLasso-class" sur la première ligne est obligatoire: il introduit l'alias du nom de la classe.
  • La seconde ligne introduit la partie "Description" du help-file.
  • La partie "details" apparaitra dans la partie "Objects from the Class".
  • Les méthodes de la classe, s'il y en a, apparaitront automatiquement dans la partie "Methods": pas besoin de les citer explicitement.

Résumé des principes balises

la description de la fonction :
  • Après le mot function ou function(:
    sur une ou plusieurs lignes introduites par ###. Les lignes-suite sont introduites par ###
  • Après ##description<<:
    n'importe où dans le source. Les lignes-suite sont introduites par ##
la description d'un argument:
Après , argument ou argument, ou argument==qqche:
  • si la description est sur la même ligne que l'argument lui-même, après ##<<. Les lignes-suite sont introduites par ##
  • si la description est sur les lignes suivant l'argument, elle est introduite par ###. Les lignes-suite sont introduites par ###
la description du retour de la fonction:
Avant l'accolade fermant la fonction, sur une ou plusieurs lignes introduites par ###
les autres clauses:
N'importe où, introduites par "##mark<<" où mark est une balise de paragraphe Rd: details, note, references, seealso, keyword Les lignes-suite sont introduites par ##

Voir aussi