Comment documenter correctement les méthodes S4 avec roxygen2

J’ai vu des discussions dans SO et à d’autres endroits sur la façon dont cela devrait être ou sera fait dans les futures versions de Roxygen2. Cependant, je suis coincé. Comment dois-je procéder pour documenter un générique S4, ainsi que ses méthodes, en utilisant Roxygen2? Un exemple pratique pour un tout nouveau générique / de nouvelles méthodes, ainsi qu’un exemple d’extension de base générique S4 serait extrêmement utile. Je ne veux pas avoir à faire de la documentation séparée (principalement) redondante pour chaque méthode S4 du même générique.

Diligence raisonnable: J’ai trouvé un exemple utile pour la méthode “extraire”. Cependant, il semble être obsolète et incomplet pour ma question. Il utilise la balise @slot dans la documentation de la classe, qui n’est pas (plus?) Prise en charge. Il ne montre qu’une extension d’une méthode S4 de base “[“, plutôt qu’un exemple complet de Roxygen incluant la documentation du générique S4.

Comment documenter correctement les méthodes S4 “[” et “[<-" en utilisant roxygen?

Si je documente complètement un nouveau générique S4 avec titre, description @param @return @name @aliases @docType @rdname , puis documentez la méthode S4 avec juste le @name @aliases @docType @rdname , j’obtiens le R CMD check avertissement de R CMD check :

 * checking for missing documentation ensortinges ... WARNING Undocumented S4 methods: <> All user-level objects in a package (including S4 classes and methods) should have documentation ensortinges. 

Il a d’abord semblé qu’aucune de mes méthodes S4 documentées de cette manière avec Roxygen2 n’avait réellement fonctionné. Cependant, jusqu’à présent, j’ai remarqué que mes extensions de la méthode principale “show” n’ont pas d’erreur associée, même si elles ont été documentées exactement de la même manière que les autres. Voici un exemple de la documentation complète de roxygen que j’ai incluse ci-dessus l’une des méthodes show, qui n’a pas généré l’erreur de documentation manquante:

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

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

 generic,signature_list-method. 

D’une manière ou d’une autre, cela n’est pas complètement compris par la R CMD check .

Enfin, après avoir construit la documentation en utilisant:

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

et en construisant le paquet, j’obtiens la documentation de fonctionnement. Tous les titres de la documentation d’une méthode spécifique se retrouvent dans le champ «Description», plutôt maladroitement. Roxygen2 a donc 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 inquiétant de la part de

 > R CMD check mypkgname 

J’ai regardé les fichiers Rd, mais je sais encore moins à leur sujet pour voir rapidement quel est le problème, et je veux de toute façon connaître la solution roxygen2 afin de ne pas avoir à manipuler les fichiers Rd directement après chaque révision de la documentation.

Donc, ceci est une question en plusieurs parties:

  1. Quelle est l’approche recommandée actuellement pour la documentation des méthodes S4 Generic et S4 avec roxygen2?

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

  3. Quelle pourrait être la cause et la solution de l’avertissement que la documentation de la plupart des méthodes S4 est manquante (même si les méthodes avec la documentation “manquante” ont en fait été traitées par roxygen2 et que les fichiers Rd résultants sont au moins assez bons pour fonctionner) dans le paquet après R CMD build mypkgname )?

    Support officiel, expliqué dans devtools doc

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

    Le court exemple actuel 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 de S3, S4 et RC via roxygen / devtools. L'explication devrait être considérée comme remplaçant l'ancienne réponse ci-dessous, qui fonctionne pour le moment, mais est moins claire et plus compliquée.

    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 

    helloworld-methods est remplacé par the_name_of_your_generic-methods . Ce sera le nom du fichier Rd contenant la documentation du générique et de toutes ses méthodes. Cette convention de dénomination n'est pas obligatoire, mais commune et utile. Le tag @export est nécessaire maintenant qu'un espace de noms est requirejs pour votre package et que vous souhaitez que cette méthode soit disponible pour les utilisateurs de votre package, et pas seulement pour les autres méthodes / fonctions de votre package.

    Pour les méthodes de documentation, je trouve que seules deux lignes sont nécessaires, fournissant les @rdname et @aliases . L'instruction @rdname doit correspondre exactement à celle du générique. La balise @aliases doit respecter une convention de dénomination décrite dans la section de documentation S4 officielle de Writing R Extensions .

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

    Il ne devrait y avoir aucun espace après les virgules dans le nom de @aliases . Je ne connais pas les règles exactes entourant l'ajout ,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 de @aliases doit correspondre au nombre d'éléments du vecteur de signature le plus long parmi les méthodes. Dans l'exemple ci-dessous, l'une des méthodes est définie avec une signature à 2 éléments, de sorte que la R CMD check n'était pas satisfaite avec la documentation sauf si ,ANY était ajouté à la balise d'alias des autres méthodes, même si leur définition un élément.

    Un exemple complet suit. Je l'ai construit et il fonctionne sans avertissement au niveau de la documentation de la part de R CMD check testpkg , en utilisant un fork corrigé d' un bogue d'une version devel très récente de roxygen2 (que j'ai mise à disposition) . Pour une installation rapide de cette fourche sur votre système, utilisez la library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") . La version la plus récente de roxygen2 ne fonctionnera pas à ce moment-là à cause d'une erreur de cotation (décrite dans une réponse séparée), mais je pense que cela sera très bientôt incorporé et que mon fork ne sera pas nécessaire. En examinant cet exemple dans le contexte d'un paquet, et en consultant les fichiers de documentation (Rd) obtenus, je l'ai rendu disponible sous la forme d'un package de test sortingvial 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("thisismyssortingng") #' helloworld(char2helloworld("thisismyssortingng")) #' helloworld(masortingx(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 à une méthode distincte, car vos méthodes ne diffèrent pas énormément du comportement auquel on s'attendrait en fonction de la doc générique. Il y a des moyens dans roxygen2 pour gérer ce cas alternatif en utilisant la balise @usage , mais les détails seraient mieux gérés par une question SO séparée.

    Donc, la plupart de vos efforts de documentation vont dans l'en-tête Roxygen au-dessus de la définition générique. Cela a une base dans le code, puisque le générique doit inclure tous les arguments spécifiques apparaissant dans les méthodes définies ultérieurement. Notez que les arguments qui sont traités dans le cadre de ... dans la liste des arguments ne sont pas inclus et ne doivent pas être documentés spécifiquement, mais le ... lui-même doit également être documenté au-dessus du générique (voir l'exemple ci-dessous).

    Pour plus de détails sur les bases de la documentation des fonctions, il y a un wiki en cours , l' ancienne vignette roxygen , ainsi que le site de développement roxygen2 sur github . Il y a aussi une question SO sur la documentation R avec Roxygen en général.

    J’ai trouvé que la réponse à la partie (3) – la documentation non manquante des méthodes S4 – est due aux guillemets ajoutés de manière erronée autour des balises \ alias lorsque la convention de dénomination S4 est utilisée; Très probablement un bug résultant du traitement de texte d’un alias qui contient une virgule dans son nom. Ceci est toujours vrai pour la dernière version de roxygen2 au moment de cette publication. Je viens de poster une description plus complète du bug avec un exemple reproductible sur la page goxygub de roxygen2:

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

    Brièvement,

     #' @aliases show,helloworld-method 

    devient

     \alias{"show,helloworld-method"} 

    dans le fichier Rd résultant. La suppression des guillemets supprime l’avertissement de R CMD check et la documentation est créée et fonctionne dans les deux cas.

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