web-dev-qa-db-fra.com

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

Pour documenter les classes avec roxygen (2), la spécification d'un titre et d'une description/détails semble être la même que pour les fonctions, les méthodes, les données, etc. Cependant, les emplacements et l'héritage 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é la mention d'une balise @slot Dans les premières descriptions de roxygen. n article de la liste de diffusion R-forge 2008 semble indiquer que c'est mort, et il n'y a pas de support pour @slot Dans roxygen:

Est-ce vrai pour 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 \describe, \item Pour documenter les emplacements semble incohérente avec le reste de roxygen (2), en ce sens qu'il n'y a pas de balises délimitées par @ et les emplacements pourraient rester non documentés sans objection de roxygenize(). Il ne dit rien non plus sur un moyen cohérent de documenter l'héritage de la classe en cours de définition. J'imagine que la dépendance fonctionne généralement bien (si un emplacement particulier nécessite une classe non-base d'un autre package) en utilisant la balise @import.

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

Il semble qu'il y ait actuellement trois options à considérer:

  • A - Liste détaillée (comme l'exemple ci-dessus).
  • B - @slot ... mais avec des balises/implémentations supplémentaires j'ai raté. Je n'ai pas réussi à faire fonctionner @slot 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 - Une balise alternative pour spécifier les emplacements, comme @param, Qui accomplirait la même chose.

J'emprunte/étends cette question d'un article que j'ai fait sur la page de développement de roxygen2 Sur github .

classrs4slotroxygen2
301
Paul McMurdie

roxygen2 v4.1 + et le dernier doc 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 cela fonctionne pour moi pour S4 maintenant.

Précédemment

Il semble que les emplacements de classe S4 soient entièrement pris en charge 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 utilisaient @alias et @usage, et comptez simplement sur roxygen2 pour faire ce qu'il faut. "

14
Paul McMurdie

Réponse mise à jour pour Roxygen2 5.0.1, actuelle à partir de 6.0.1

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

#' 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 façon générale d'exporter une fonction est d'utiliser @export à présent. Vous n'avez pas non plus à 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

Réponse mise à jour pour Roygen2 3.0.0, actuelle à partir de 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 emplacements sous forme de liste à l'intérieur de l'objet. Comme vous le faites remarquer, cette syntaxe est différente de celle des autres lignes, et nous pouvons espérer à l'avenir une solution plus robuste intégrant la connaissance de l'héritage - mais aujourd'hui, elle n'existe pas.

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

28
William Entriken

La solution fournie par Full Decent est OK si vous optez pour la documentation des emplacements dans les fichiers Rd eux-mêmes. Lors de l'utilisation de roxygen2, vous pouvez utiliser la balise @section faire essentiellement 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}:}{Matrix 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
18
Joris Meys