Comment documenter correctement les emplacements de classe S4 à l'aide de RoxyGen2?

Question

Pour documenter les classes avec Roxygen (2), la spécification d'un titre et des description / détails semble être la même que pour les fonctions, les méthodes, les données, etc. Cependant, les machines à sous et l'héritage sont leur propre sorte d'animal. Quelle est la meilleure pratique - actuelle ou planifiée - pour documenter les classes S4 dans RoxyGen2?

Vérifications nécessaires:

J'ai trouvé une mention d'un @slot Tag dans les premières descriptions de Roxygen.Une publication de liste de diffusion R-Forge 2008 semble indiquer que c'est mort, et il n'y a aucun soutien à @slot Dans Roxygen:

Est-ce vrai pour Roxygen2? La publication mentionnée précédemment suggère qu'un utilisateur devrait plutôt faire sa propre liste détaillée avec le balisage de latex. Par exemple une nouvelle classe S4 qui étend le "character" La 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, ceci \describe , \item L'approche pour documenter les machines à sous semble incompatible avec le reste de Roxygen (2), en ce qu'il n'y a pas @-Les étiquettes et fentes dédiées pourraient devenir sans papiers sans objection de roxygenize(). Il ne dit pas non plus une façon cohérente de documenter l'héritage de la définition de la classe. J'imagine que la dépendance fonctionne toujours bien (si un emplacement particulier nécessite une classe non-base d'un autre package) en utilisant le @import étiquette.

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

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

• A - Liste détaillée (comme exemple ci-dessus).
• B - @slot ... Mais avec des balises / implémentation supplémentaires, j'ai manqué. Je n'ai pas pu faire fonctionner @slot avec Roxygen / Roxygen2 dans les versions où il a été 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 étiquette alternative pour spécifier les emplacements, comme @param, cela accomplirait la même chose.

J'emprunte / étend cette question à un post que j'ai fait au roxygen2 page de développement sur github.

Answer 1

Roxygen2 v4.1 + et le dernier document de Hadley pour faire ceci:

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 la version 3.0+ de RoxyGen2:

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

"Documentez vos classes S4, les méthodes S4 et les classes RC avec RoxyGen2 - vous pouvez supprimer en toute sécurité des solutions de contournement @alias et @usage, et comptez simplement sur Roxygen2 pour faire la bonne chose. "

Answer 2

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

Pour S4, la meilleure pratique est maintenant de documenter en utilisant le @slot étiquette:

#' 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 utilise @export à présent. Vous n'avez pas non plus à exporter une classe, à moins que vous souhaitiez que d'autres packages puissent prolonger la classe.

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

Réponse mise à jour pour Roygen2 3.0.0, courant en 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"}.}
#'    }
#'  }

Cela est cohérent avec la représentation interne des emplacements comme liste à l'intérieur de l'objet. Comme vous le soulignez, cette syntaxe est différente des autres lignes, et nous pouvons espérer une solution plus robuste à l'avenir qui intègre la connaissance de l'héritage - mais aujourd'hui qui n'existe pas.

Comme l'a souligné @brian diggs, cette fonction a été entraînée dans 3,0,0, discussion plus approfondie à https://github.com/klutometis/roxygen/pull/85

Answer 3

La solution fournie par Full Decent est OK si vous optez pour documenter les emplacements dans les fichiers RD lui-même. Lors de l'utilisation roxygen2, vous pouvez utiliser la balise @section faire fondamentalement 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