Comment documenter correctement les méthodes S4 en utilisant roxygen2

Question

J'ai vu des discussions en SO et d'autres lieux en ce qui concerne la façon dont cela devrait être ou sera fait dans les versions futures de Roxygen2. Cependant, je suis coincé. Comment dois-je aller sur la documentation d'un générique S4, ainsi que ses méthodes, en utilisant Roxygen2? Un exemple de travail pour une marque de nouvelles méthodes de / génériques, ainsi qu'un exemple pour la base S4 extension générique serait incroyablement utile. Je ne veux pas avoir à faire à part (la plupart du temps) la documentation redondante pour chaque méthode S4 du même générique.

En raison dilligence: J'ai traqué un exemple utile pour la méthode « extrait ». Cependant, il semble être obsolète et incomplète pour ma question. Il utilise balise @slot dans la documentation de la classe, qui ne sont pas (plus?) Pris en charge. Il montre qu'une extension d'une méthode S4 de base « [ », plutôt que d'un exemple complet Roxygen y compris la documentation du générique S4.

Comment documenter correctement S4 "[" et « [ <- « méthodes utilisant roxygen

Si je documenter une nouvelle S4 générique avec le titre, la description @param @return @name @aliases @docType @rdname et Documentez ensuite la méthode S4 avec juste le @name @aliases @docType @rdname correspondant, je reçois l'avertissement R CMD check suivant:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

Il regarda d'abord comme si aucun de mes méthodes S4 documentées dans ce mode avec roxygen2 avait effectivement travaillé. Cependant, jusqu'à présent, je l'ai remarqué que mes extensions de la méthode de base « show » ne sont pas une erreur associée, même si elles ont été documentées exactement de la même manière que le reste. Voici un exemple de la documentation complète roxygen I inclus ci-dessus l'une des méthodes d'exposition, qui ne génère pas l'erreur manquante-documentation:

#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods

Ainsi, je suis à une perte. Comme vous pouvez le voir, j'ai inclus la convention pour les alias des méthodes S4 décrites dans la section de documentation S4 du paquet R manuel, à savoir que les méthodes doivent avoir un alias avec le nom suivant (sans espace):

generic,signature_list-method.

D'une certaine façon, ce n'est pas complètement être compris par R CMD check.

Enfin, après la construction de la documentation à l'aide:

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

et la construction du paquet, j'obtenir de la documentation qui fonctionne. Tous les titres d'une documentation de méthode spécifique vents dans le champ « Description », plutôt maladroitement. Alors roxygen2 évidemment fait quelque chose avec la documentation de chaque méthode et est sur la bonne voie. Cependant, il ne suffit pas d'éviter un avertissement important et troublant de

> R CMD check mypkgname

Je l'ai regardé les fichiers Rd, mais je sais encore moins sur eux pour voir rapidement quel est le problème, et je veux de toute façon de connaître la solution roxygen2 pour que je ne vais pas avoir à manipuler les fichiers Rd directement après chaque révision des documents.

C'est donc une question multipart:

1. Quelle est l'approche recommandée actuelle pour les documents de méthode générique et S4 S4 avec roxygen2?

2. Y at-il un bon exemple disponible quelque part qui montre les détails?

3. Quelle pourrait être la cause et la solution, la mise en garde que la documentation pour la plupart des méthodes S4 est manquante (même si les méthodes avec « disparus » documents ont effectivement eu leur doc analysé par roxygen2 et les fichiers Rd résultants sont au moins assez bon pour travailler dans l'emballage après R CMD build mypkgname)?

Answer 1

Soutien officiel, a expliqué dans devtools doc

http://r-pkgs.had.co.nz/ man.html # man-classes (Faites défiler jusqu'à la S4 du paragraphe).

L'exemple courant de court de cette page est reproduite ci-après (pour des raisons pratiques):

#' 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 S3, S4 et support RC via roxygen / devtools. L'explication, il doit être considéré remplacer la réponse ci-dessous plus, ce qui fonctionne pour l'instant, mais il est moins clair et plus compliqué.

La vieille réponse

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

Pour la documentation génériques S4, je trouve les trois lignes nécessaires dans la plupart de mes en-têtes génériques suivants:

#' @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 détient la documentation pour le générique et toutes ses méthodes. Cette convention d'appellation n'est pas nécessaire, mais commun et utile. La balise @export est nécessaire maintenant qu'un espace de noms est requis pour votre package et que vous souhaitez que cette méthode soit disponible pour les utilisateurs de votre colis, et non seulement d'autres méthodes / fonctions dans votre package.

Pour documenter les méthodes, je trouve que seulement deux lignes sont nécessaires, fournissant la balise @rdname et @aliases. La déclaration de @rdname doit correspondre exactement à celui du générique. La balise @aliases doit adhérer à une convention de nommage décrite dans la section documentation officielle de S4 écriture R Extensions .

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

Il ne doit y avoir aucun espace après les virgules dans le nom de @aliases. Je ne connais pas les règles exactes de quand ajouter ,ANY à la fin de la liste des signatures. Le modèle semble être que le nombre d'éléments dans toutes les listes de signatures @aliases doit correspondre au nombre d'éléments dans le vecteur de signature la plus longue parmi les méthodes. Dans l'exemple ci-dessous, l'une des méthodes est définie avec la signature 2 éléments, et ainsi R CMD check n'a pas été satisfait de la documentation, sauf si ,ANY a été ajouté au alias étiquette des autres méthodes, même si leur définition de la signature n'a qu'un seul élément.

Un exemple complet suit. J'ai construit cela et il fonctionne sans avertissement au niveau de la documentation de R CMD check testpkg, en utilisant un bug fixe fourche d'une très récente version de développement de roxygen2 (que je mis à la 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 me attends ce sera intégré très rapidement et ma fourchette ne sera pas nécessaire. Pour regarder cet exemple dans le contexte du reste d'un paquet, et de voir la documentation résultant des fichiers (Rd), je l'ai fait disponible en tant que paquet de 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 spécifique à la méthode séparée parce que vos méthodes ne sont pas follement viré de celui du comportement serait sur la estimation prévue doc générique. Il existe des moyens de roxygen2 pour traiter ce cas alternatif en utilisant la balise @usage, mais les détails seraient mieux traitées par une autre question de SO.

Ainsi, la plupart de vos efforts de documentation va dans l'en-tête de roxygen ci-dessus la définition générique. Cela a une base dans le code, car le générique doit 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 dans le cadre dela ... dans la liste des arguments ne sont pas inclus et ne doit pas être documenté en particulier, mais le ... lui-même doit être documentée au-dessus du générique et (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 , ancienne vignette roxygen , ainsi que la site de développement roxygen2 sur github . Il y a aussi un SO question sur la documentation R avec Roxygen en général.

Answer 2

J'ai traqué que la réponse à la partie (3) - la documentation pas si manque de méthodes S4 - est à cause de guillemets étant ajouté par erreur dans les tags \ alias quand est utilisé la convention de nommage S4; très probablement un bug résultant d'un texte de traitement d'un alias qui contient une virgule dans le cadre de son nom. Cela est encore vrai de la dernière version de roxygen2 au moment de cette annonce. Je viens de publier une description plus complète du bogue avec un exemple reproductible sur la page github roxygen2:

https://github.com/klutometis/roxygen/issues/40

En bref,

#' @aliases show,helloworld-method

devient

\alias{"show,helloworld-method"}

dans le fichier Rd résultant. La suppression des citations supprime l'avertissement R CMD check et la documentation construit et est fonctionnel dans les deux cas.

Je pense que les parties (1) et (2) de cette question (les meilleures pratiques, de bons exemples) se tiennent toujours ouvert.