Comment bien documenter les méthodes S4 en utilisant roxygen2

soutien officiel, expliqué dans devtools doc

http://r-pkgs.had.co.nz/man.html#man-classes (faites défiler vers le bas jusqu'à la sous-section S4 ).

le court exemple actuel tiré de cette page est reproduit ci-après (pour plus de commodité):

#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

le lien ci-dessus explique très clairement le support S3, S4, et RC via roxygen/devtools. L'explication n' doit être considéré comme remplacent les anciens réponse ci-dessous, ne fonctionne pour l'instant, mais est moins claire et plus compliqué.

l'ancienne réponse

voici un exemple qui devrait fonctionner pour la plupart des méthodes S4.

pour documenter les génériques S4, je trouve les trois lignes suivantes nécessaires dans la plupart de mes en-têtes génériques:

#' @export
#' @docType methods
#' @rdname helloworld-methods

où helloworld-methods est remplacé par the_name_of_your_generic-methods . Ce sera le nom du fichier Rd qui contient la documentation pour le générique et toutes ses méthodes. Cette convention d'appellation n'est pas nécessaire, mais elle est courante et utile. La balise @export est nécessaire maintenant qu'un namespace est requis pour votre paquet et que vous voulez que cette méthode soit disponible pour les utilisateurs de votre paquet, pas seulement d'autres méthodes/fonctions dans votre paquet.

pour documenter les méthodes, je trouve que seulement 2 lignes sont nécessaires, fournissant la balise @rdname et @aliases . L'énoncé @rdname devrait correspondre exactement à celui du générique. L'étiquette @aliases doit adhérer à une convention de nommage décrite dans la section de documentation officielle S4 de Writing R Extensions .

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method

il ne doit pas y avoir d'espaces après les virgules dans le nom @aliases . Je ne connais pas les règles exactes entourant quand ajouter ,ANY à la fin de la liste de signature. Le motif semble être que le nombre de les éléments de tous les @aliases signature des listes doit correspondre au nombre d'éléments dans la plus longue de la signature de vecteur entre les méthodes. Dans l'exemple ci-dessous, une des méthodes est définie avec une signature à 2 éléments, et donc R CMD check n'était pas satisfait de la documentation à moins que ,ANY n'ait été ajouté à la balise d'Alias des autres méthodes, même si leur définition de signature n'a qu'un élément.

un exemple complet suit. Je l'ai construit et il fonctionne avec aucun avertissements de niveau de documentation de R CMD check testpkg , en utilisant un fourche bug-fixed d'une version de développement très récente de roxygen2 (que j'ai mis à disposition) . Pour une installation rapide de cette fourche sur votre système, utilisez library("devtools"); install_github("roxygen", "joey711") . La version la plus récente de roxygen2 ne fonctionnera pas à ce moment en raison d'une erreur de citation (décrite dans une réponse séparée), mais je m'attends à ce que cela sera incorporé très bientôt et ma fourchette ne sera pas nécessaire. Pour avoir examiné cet exemple dans le contexte de reste d'un paquet, et en voyant les fichiers de documentation résultants (Rd), Je l'ai rendu disponible comme un paquet test trivial sur github appelé testpkg .

##############################################################
#' The title, in this case: Helloworld-ify the argument.
#'
#' Some additional details about this S4 generic and its methods.
#' The extra blank line between this section and the title is
#' critical for roxygen2 to differentiate the title from the
#' description section.
#'
#' @param x Description of \code{x}. The main argument in this
#'  example. Most often has such and such properties.
#'
#' @param y Description of \code{y}. An argument that is rarely
#'  used by \code{"helloworld"} methods. 
#'
#' @param ... Additional argument list that might not ever
#'  be used.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#' 
#' @seealso \code{\link{print}} and \code{\link{cat}}
#' 
#' @export
#' @docType methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
#' helloworld(char2helloworld("thisismystring"))
#' helloworld(matrix(0,3,3))
#' helloworld(list(0,0,0))
#' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
    cat("Hello World!")
    cat("\n")
    standardGeneric("helloworld")
})

#' @rdname helloworld-methods
#' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
    cat(class(x))
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
    show(x)
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
    show(x)
})

cet exemple suppose que vous n'avez pas besoin de documentation séparée spécifique à la méthode parce que vos méthodes n'ont pas dévié sauvagement du comportement que l'on attendrait basé sur le doc Générique. Il y a des moyens dans roxygen2 pour gérer ce cas alternatif en utilisant l'étiquette @usage , mais les détails seraient mieux traités par une question séparée.

ainsi la plupart de vos efforts de documentation va dans l'en-tête roxygen au-dessus de la définition générique. Cela a une certaine base dans le code, puisque le générique devrait inclure tous les arguments spécifiques qui apparaissent dans l'une des méthodes définies par la suite . Notez que les arguments qui sont traités comme faisant partie du ... dans la liste des arguments ne sont pas inclus et ne devraient pas être documentés spécifiquement, mais ... lui-même doit être documentée au-dessus du générique (voir l'exemple complet ci-dessous).

pour plus de détails sur les bases de la Documentation des fonctions, il y a un wiki en cours , le vieille vignette roxygen , ainsi que le roxygen2 site de développement sur GitHub . Il ya aussi un donc question sur la documentation R avec Roxygen en général.