So dokumentieren Sie S4-Methoden mit roxygen2 richtig

Question

Ich habe in SO und an anderen Orten einige Diskussionen darüber gesehen, wie dies in zukünftigen Versionen von Roxygen2 erfolgen sollte oder geschehen wird.Allerdings stecke ich fest.Wie soll ich bei der Dokumentation eines S4-Generikums und seiner Methoden mit Roxygen2 vorgehen?Ein funktionierendes Beispiel für ein brandneues Generikum/Methoden sowie ein Beispiel für die Erweiterung des Basis-S4-Generikums wären unglaublich nützlich.Ich möchte nicht für jede S4-Methode desselben Generikums eine separate (meist) redundante Dokumentation erstellen müssen.

Due Diligence:Ich habe ein nützliches Beispiel für die Methode „Extrahieren“ gefunden.Für meine Frage scheint es jedoch veraltet und unvollständig zu sein.Es verwendet das @slot-Tag in der Klassendokumentation, das nicht (mehr?) unterstützt wird.Es zeigt nur eine Erweiterung einer S4-Kernmethode „[“ und kein vollständiges Roxygen-Beispiel einschließlich der Dokumentation des S4-Generikums.

Wie dokumentiere ich die S4-Methoden „[“ und „[<-“ unter Verwendung von Sauerstoff richtig?

Wenn ich ein neues S4-Generikum vollständig mit Titel und Beschreibung dokumentiere @param @return @name @aliases @docType @rdname, und dokumentieren Sie dann die S4-Methode nur mit dem entsprechenden @name @aliases @docType @rdname, ich bekomme Folgendes R CMD check Warnung:

* 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.

Es sah zunächst so aus, als hätte keine meiner auf diese Weise dokumentierten S4-Methoden mit Roxygen2 tatsächlich funktioniert.Bisher ist mir jedoch aufgefallen, dass meine Erweiterungen der Kernmethode „show“ keinen zugehörigen Fehler aufweisen, obwohl sie genauso dokumentiert wurden wie der Rest.Hier ist ein Beispiel der vollständigen Sauerstoffdokumentation, die ich über einer der Show-Methoden eingefügt habe, die NICHT den Fehler wegen fehlender Dokumentation erzeugt hat:

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

Daher bin ich ratlos.Wie Sie sehen können, habe ich die in beschriebene Konvention für Aliase für S4-Methoden eingefügt den S4-Dokumentationsabschnitt des R-Pakethandbuchs, nämlich dass Methoden einen Alias ​​mit folgendem Namen (ohne Leerzeichen) haben sollten:

generic,signature_list-method.

Irgendwie wird das nicht ganz verstanden R CMD check.

Schließlich, nach dem Erstellen der Dokumentation mit:

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

und beim Erstellen des Pakets erhalte ich eine funktionierende Dokumentation.Alle Titel aus der Dokumentation einer bestimmten Methode landen ziemlich umständlich im Feld „Beschreibung“.Also hat roxygen2 offensichtlich etwas mit der Dokumentation jeder Methode gemacht und ist auf dem richtigen Weg.Es reicht jedoch nicht aus, eine große und beunruhigende Warnung zu vermeiden

> R CMD check mypkgname

Ich habe mir die Rd-Dateien angesehen, aber ich weiß noch weniger darüber, um schnell zu erkennen, wo das Problem liegt, und ich möchte sowieso die Roxygen2-Lösung kennen, damit ich die Rd-Dateien nicht direkt nach jeder Überarbeitung der Dokumentation manipulieren muss.

Das ist also eine mehrteilige Frage:

1. Was ist der derzeit empfohlene Ansatz für die S4-Generika- und S4-Methodendokumentation mit roxygen2?

2. Gibt es irgendwo ein gutes Beispiel, das alle Details zeigt?

3. Was könnte die Ursache und Lösung für die Warnung sein, dass die Dokumentation für die meisten S4-Methoden fehlt (obwohl die Dokumentation der Methoden mit „fehlender“ Dokumentation tatsächlich von roxygen2 analysiert wurde und die resultierenden Rd-Dateien zumindest gut genug sind, um zu funktionieren? im Paket nach R CMD build mypkgname) ?

Answer 1

Offizieller Support, erklärt im Devtools-Dokument

http://r-pkgs.had.co.nz/man.html#man-classes(Scrollen Sie nach unten zu S4 Unterabschnitt).

Das aktuelle kurze Beispiel von dieser Seite wird im Folgenden wiedergegeben (der Einfachheit halber):

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

Der obige Link erklärt sehr deutlich die S3-, S4- und RC-Unterstützung über roxygen/devtools.Die dortige Erklärung sollte als Ersatz für die ältere Antwort unten betrachtet werden, die vorerst zwar funktioniert, aber weniger klar und komplizierter ist.

Die alte Antwort

Hier ist ein Beispiel, das für die meisten S4-Methoden funktionieren sollte.

Zur Dokumentation von S4-Generika halte ich in den meisten meiner generischen Header die folgenden drei Zeilen für notwendig:

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

Wo helloworld-methods wird durch ersetzt the_name_of_your_generic-methods.Dies ist der Name der Rd-Datei, die die Dokumentation für das Generikum und alle seine Methoden enthält.Diese Namenskonvention ist nicht erforderlich, aber üblich und nützlich.Der @export -Tag ist nun erforderlich, da für Ihr Paket ein Namespace erforderlich ist und Sie möchten, dass diese Methode den Benutzern Ihres Pakets zur Verfügung steht, nicht nur anderen Methoden/Funktionen in Ihrem Paket.

Für die Dokumentation von Methoden sind meiner Meinung nach nur zwei Zeilen erforderlich, die Folgendes bereitstellen @rdname Und @aliases Etikett.Der @rdname Die Anweisung sollte genau mit der für das Generikum übereinstimmen.Der @aliases Das Tag muss einer Namenskonvention entsprechen, die im Abschnitt zur offiziellen S4-Dokumentation von beschrieben ist Schreiben von R-Erweiterungen.

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

Nach den Kommas dürfen keine Leerzeichen stehen @aliases Name.Ich kenne die genauen Regeln für das Hinzufügen nicht ,ANY bis zum Ende der Unterschriftenliste.Das Muster scheint die Anzahl der Elemente insgesamt zu sein @aliases Signaturlisten müssen mit der Anzahl der Elemente im längsten Signaturvektor der Methoden übereinstimmen.Im folgenden Beispiel ist eine der Methoden mit einer 2-Element-Signatur usw. definiert R CMD check war mit der Dokumentation nicht zufrieden, es sei denn ,ANY wurde dem Aliases-Tag der anderen Methoden hinzugefügt, auch wenn deren Signaturdefinition nur ein Element enthält.

Es folgt ein vollständiges Beispiel.Ich habe das erstellt und es funktioniert ohne Warnungen auf Dokumentationsebene R CMD check testpkg, Verwendung einer Fehler behobener Fork einer sehr aktuellen Entwicklungsversion von roxygen2 (die ich zur Verfügung gestellt habe).Für eine schnelle Installation dieses Forks auf Ihrem System verwenden Sie library("devtools"); install_github("roxygen", "joey711").Die neueste Version von roxygen2 wird derzeit aufgrund eines Zitatfehlers (in einer separaten Antwort beschrieben) nicht funktionieren, aber ich gehe davon aus, dass dies sehr bald integriert wird und mein Fork nicht erforderlich sein wird.Um dieses Beispiel im Kontext des Rests eines Pakets zu betrachten und die resultierenden Dokumentationsdateien (Rd) anzuzeigen, habe ich es als triviales Testpaket auf Github mit dem Namen verfügbar gemacht 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)
})

In diesem Beispiel wird davon ausgegangen, dass Sie keine separate methodenspezifische Dokumentation benötigen, da Ihre Methoden nicht stark von dem Verhalten abweichen, das man aufgrund des generischen Dokuments erwarten würde.Es gibt Mittel in roxygen2, um diesen alternativen Fall mithilfe von zu behandeln @usage Tag, aber die Details würden besser in einer separaten SO-Frage behandelt.

Daher fließt der größte Teil Ihres Dokumentationsaufwands in den Roxygen-Header oberhalb der generischen Definition.Dies hat eine gewisse Grundlage im Code, da das Generikum alle spezifischen Argumente enthalten sollte, die in einer der nachfolgend definierten Methoden vorkommen.Beachten Sie, dass Argumente, die als Teil von behandelt werden ... in der Argumentliste sind nicht enthalten und sollten nicht speziell dokumentiert werden, aber die ... selbst sollte ebenfalls über dem generischen Dokument dokumentiert werden (siehe das vollständige Beispiel unten).

Weitere Einzelheiten zu den Grundlagen der Dokumentation von Funktionen finden Sie unter a Wiki in Bearbeitung, Die alte Sauerstoffvignette, ebenso wie roxygen2-Entwicklungsseite auf Github.Da ist auch ein SO Frage zur R-Dokumentation mit Roxygen Im Algemeinen.

Answer 2

Ich habe herausgefunden, dass die Antwort auf Teil (3) – die nicht ganz so fehlende Dokumentation von S4-Methoden – darauf zurückzuführen ist, dass bei Verwendung der S4-Namenskonvention fälschlicherweise Anführungszeichen um die \alias-Tags eingefügt wurden;höchstwahrscheinlich ein Fehler, der aus der Textverarbeitung eines Alias ​​resultiert, dessen Name ein Komma enthält.Dies gilt immer noch für die neueste Version von roxygen2 zum Zeitpunkt dieses Beitrags.Ich habe gerade eine ausführlichere Beschreibung des Fehlers mit einem reproduzierbaren Beispiel auf der Github-Seite von roxygen2 gepostet:

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

Knapp,

#' @aliases show,helloworld-method

wird

\alias{"show,helloworld-method"}

in der resultierenden Rd-Datei.Durch das Entfernen der Anführungszeichen wird das entfernt R CMD check Warnung, und die Dokumentation wird erstellt und ist in beiden Fällen funktionsfähig.

Ich denke, die Teile (1) und (2) dieser Frage (Best Practices;gute Beispiele) sind noch offen.