Comment documenter correctement les slots de classe S4 en utilisant Roxygen2?

Pour documenter les classes avec roxygen (2), spécifier un titre et une description / détails semble être le même que pour les fonctions, les méthodes, les données, etc. Cependant, les slots et l’inheritance sont leur propre type d’animal. Quelle est la meilleure pratique – actuelle ou prévue – pour documenter les classes S4 dans roxygen2?

Vérifications nécessaires:

J’ai trouvé une mention d’une balise @slot dans les premières descriptions de roxygen. Un article de la liste de diffusion R-forge 2008 semble indiquer qu’il est mort et qu’il n’y a pas de support pour @slot dans roxygen:

Est-ce vrai de roxygen2? Le message mentionné précédemment suggère qu’un utilisateur devrait plutôt créer sa propre liste détaillée avec le balisage LaTeX. Par exemple, une nouvelle classe S4 qui étend la classe "character" serait codée et documentée comme ceci:

 #' The title for my S4 class that extends \code{"character"} class. #' #' Some details about this class and my plans for it in the body. #' #' \describe{ #' \item{myslot1}{A logical keeping track of something.} #' #' \item{myslot2}{An integer specifying something else.} #' #' \item{myslot3}{A data.frame holding some data.} #' } #' @name mynewclass-class #' @rdname mynewclass-class #' @exportClass mynewclass setClass("mynewclass", representation(myslot1="logical", myslot2="integer", myslot3="data.frame"), contains = "character" ) 

Cependant, bien que cela fonctionne, cette approche de \describe , \item pour documenter les slots semble incohérente avec le rest de roxygen (2), car il n’y a pas de balises délimitées par @ et les slots peuvent ne pas être documentés sans objection de roxygenize() . Il ne dit rien non plus sur un moyen cohérent de documenter l’inheritance de la classe en cours de définition. J’imagine que la dépendance fonctionne toujours très bien (si un emplacement particulier requirejs une classe autre que la base d’un autre package) en utilisant la balise @import .

Donc, pour résumer, quelle est la meilleure pratique actuelle pour les slots roxygen (2)?

Il semble y avoir trois options à considérer pour le moment:

  • A – Liste détaillée (exemple ci-dessus).
  • B – @slot … mais avec des balises / implémentations supplémentaires que j’ai manquées. Je n’ai pas pu obtenir que @slot fonctionne avec roxygen / roxygen2 dans les versions où il était inclus en remplacement de la liste détaillée dans l’exemple ci-dessus. Encore une fois, l’exemple ci-dessus fonctionne avec Roxygen (2).
  • C – Un autre tag pour spécifier des slots, comme @param , qui accomplirait la même chose.

roxygen2 / prolonge cette question d’un post que j’ai fait à la page de développement de roxygen2 sur github .

Mise à jour de la réponse pour Roxygen2 5.0.1, à partir de 6.0.1

Pour S4, la meilleure pratique consiste maintenant à documenter à l’aide de la balise @slot :

 #' The title for my S4 class that extends \code{"character"} class. #' #' Some details about this class and my plans for it in the body. #' #' @slot myslot1 A logical keeping track of something. #' @slot myslot2 An integer specifying something else. #' @slot myslot3 A data.frame holding some data. #' #' @name mynewclass-class #' @rdname mynewclass-class #' @export 

Sur un sidenote, @exportClass n’est nécessaire que dans certains cas, la manière générale d’exporter une fonction est d’utiliser @export maintenant. Vous n’avez pas non plus besoin d’exporter une classe, sauf si vous souhaitez que d’autres packages puissent étendre la classe.

Voir aussi http://r-pkgs.had.co.nz/namespace.html#exports

Mise à jour de la réponse pour Roygen2 3.0.0, à partir de la version 5.0.1.

Pour S4, la meilleure pratique est la documentation sous la forme:

 #' \section{Slots}{ #' \describe{ #' \item{\code{a}:}{Object of class \code{"numeric"}.} #' \item{\code{b}:}{Object of class \code{"character"}.} #' } #' } 

Ceci est cohérent avec la représentation interne des slots en tant que liste à l’intérieur de l’object. Comme vous le soulignez, cette syntaxe est différente de celle des autres lignes, et nous pouvons espérer une solution plus robuste intégrant la connaissance de l’inheritance – mais aujourd’hui, cela n’existe pas.

Comme l’a souligné @Brian Diggs, cette fonctionnalité a été intégrée à la version 3.0.0, une discussion plus approfondie à l’ adresse https://github.com/klutometis/roxygen/pull/85.

La solution fournie par Full Decent est correcte si vous choisissez de documenter les emplacements dans les fichiers Rd elle-même. Lorsque vous utilisez roxygen2 , vous pouvez utiliser la balise @section pour faire la même chose avec \describe . Un exemple:

 #' The EXAMPLE class #' #' This class contains an example. This line goes into the description #' #' This line and the next ones go into the details. #' This line thus appears in the details as well. #' #'@section Slots: #' \describe{ #' \item{\code{slot1}:}{Masortingx of class \code{"numeric"}, containing data from slot1} #' \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.} #' } #' #' @note You can still add notes #' @name EXAMPLE #' @rdname EXAMPLE #' @aliases EXAMPLE-class #' @exportClass EXAMPLE #' @author Joris Meys 

roxygen2 v4.1 + et le dernier document de Hadley pour ce faire:

http://r-pkgs.had.co.nz/man.html#man-classes

Je ne l’ai pas encore essayé pour RC, mais ça marche pour moi maintenant pour S4.

Précédemment

Il semble que les slots de classe S4 soient totalement supportés sous Roxygen2 version 3.0+:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

“documentez vos classes S4, méthodes S4 et classes RC avec roxygen2 – vous pouvez supprimer en toute sécurité les solutions de contournement qui ont utilisé @alias et @usage , et simplement vous fier à roxygen2 pour faire les choses correctement.”