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 @slotétiquette dans les premières descriptions de roxygen. Une publication de la liste de diffusion R-forge 2008 semble indiquer que c'est mort, et il n'y a pas de support pour@slot 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 "character"classe 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, ce \describe, \itemapproche pour documenter les fentes semble incompatible avec le reste de roxygen (2) dans la mesure où il n'y a pas de @balises et fentes -delimited pourrait aller en situation irrégulière sans objection roxygenize(). Il ne dit également rien 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 @importbalise.

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

Il semble qu'il y ait trois options à considérer pour le moment:

• A - Liste détaillée (comme l'exemple ci-dessus).
• B - @slot... mais avec des tags / 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, cela accomplirait la même chose.

J'emprunte / étend cette question à partir d'un post que j'ai fait sur la roxygen2page de développement sur github .

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

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

#' 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, @exportClassn'est nécessaire que dans certains cas, la façon générale d'exporter une fonction utilise @exportmaintenant. 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, à jour à 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

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 roxygen2, vous pouvez utiliser la balise @sectionpour 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

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/

"documenter 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é @aliaset @usage, et simplement compter sur roxygen2 pour faire la bonne chose."