Für die Dokumentation von Klassen mit Sauerstoff (2) scheint die Angabe eines Titels und einer Beschreibung / Details dieselbe zu sein wie für Funktionen, Methoden, Daten usw. Slots und Vererbung sind jedoch ihre eigene Tierart. Was ist die derzeitige oder geplante Best Practice für die Dokumentation von S4-Klassen in roxygen2?
Due Diligence:
Ich fand Erwähnung eines @slot
Tags in frühen Beschreibungen von Sauerstoff.
Ein Beitrag der R-Forge-Mailingliste von 2008
scheint darauf hinzudeuten, dass dies tot ist, und es gibt keine Unterstützung für @slot
in roxygen:
Gilt das für roxygen2? Der zuvor erwähnte Beitrag schlägt vor, dass ein Benutzer stattdessen eine eigene Auflistung mit LaTeX-Markup erstellen sollte. Beispielsweise würde eine neue S4-Klasse, die die "character"
Klasse erweitert, wie folgt codiert und dokumentiert:
#' 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"
)
Doch obwohl dies funktioniert, dies \describe
, \item
Ansatz für die Slots zu dokumentieren scheint unvereinbar mit dem Rest roxygen (2), dass es keine @
separierten Tags und Slots ohne Einwand von undokumentiert gehen könnte roxygenize()
. Es sagt auch nichts über eine konsistente Methode aus, um die Vererbung der zu definierenden Klasse zu dokumentieren. Ich stelle mir vor, dass die Abhängigkeit mit dem @import
Tag im Allgemeinen immer noch gut funktioniert (wenn für einen bestimmten Slot eine Nicht-Basisklasse aus einem anderen Paket erforderlich ist) .
Zusammenfassend lässt sich sagen, was ist die derzeitige Best Practice für Roxygen (2) -Slots?
Momentan scheinen drei Optionen in Betracht zu ziehen:
- A - Auflistung der Listen (wie im obigen Beispiel).
- B -
@slot
... aber mit zusätzlichen Tags / Implementierung habe ich verpasst. Ich konnte @slot nicht dazu bringen, mit roxygen / roxygen2 in Versionen zu arbeiten, in denen es als Ersatz für die im obigen Beispiel aufgeführte Liste enthalten war. Auch hier funktioniert das obige Beispiel mit Sauerstoff (2).- C - Ein alternatives Tag zum Festlegen von Slots, mit
@param
dem dasselbe erreicht werden kann.
Ich leihe mir diese Frage aus einem Beitrag aus, den ich auf der roxygen2
Entwicklungsseite von Github verfasst habe .
@slot
ist wahrscheinlich das, was Sie langfristig wollen, aber es muss zuerst implementiert werden ...setClass
Anweisungen enthält alssetMethod
. Die einmal vorgenommene Änderung@slot
wird nicht zu schmerzhaft sein.Antworten:
Aktualisierte Antwort für Roxygen2 5.0.1, aktuell ab 6.0.1
Für S4 ist es jetzt die beste Vorgehensweise, mit dem
@slot
Tag zu dokumentieren :Nebenbei bemerkt,
@exportClass
ist nur in einigen Fällen die allgemeine Methode zum Exportieren einer Funktion@export
jetzt verwendet. Sie müssen auch keine Klasse exportieren, es sei denn, Sie möchten, dass andere Pakete die Klasse erweitern können.Siehe auch http://r-pkgs.had.co.nz/namespace.html#exports
Aktualisierte Antwort für Roygen2 3.0.0, Stand 5.0.1.
Für S4 ist die Dokumentation die folgende Vorgehensweise:
Dies steht im Einklang mit der internen Darstellung von Slots als Liste innerhalb des Objekts. Wie Sie hervorheben, unterscheidet sich diese Syntax von anderen Zeilen, und wir hoffen möglicherweise auf eine robustere Lösung in der Zukunft, die Vererbungskenntnisse beinhaltet - aber heute gibt es diese nicht.
Wie von @Brian Diggs hervorgehoben, wurde diese Funktion in 3.0.0 integriert. Weitere Informationen finden Sie unter https://github.com/klutometis/roxygen/pull/85
quelle
@slot
Lösung) angeben? Ich bin nicht dazu gekommen, es zu versuchen und habe (vielleicht träge) auf diese anstehende@slot
Lösung gewartet . Ich weiß, dass die Frage nicht so gestellt wird, aber basierend auf Kommentaren (einschließlich @ hadleys) scheint@slot
es die "echte" Antwort zu sein. Ich stimme Ihrer Einschätzung zu, dass eine detaillierte Liste (wie in meiner Frage) die derzeitige bewährte Methode ist, die jedoch hoffentlich sehr bald ersetzt wird.Die von Full Decent bereitgestellte Lösung ist in Ordnung, wenn Sie Slots in den Rd-Dateien selbst dokumentieren. Bei der Verwendung
roxygen2
können Sie das Tag verwenden@section
, um im Grunde dasselbe mit zu tun\describe
. Ein Beispiel:quelle
roxygen2 v4.1 + und Hadleys neuestes Dokument dafür:
http://r-pkgs.had.co.nz/man.html#man-classes
Ich habe es noch nicht für RC ausprobiert, aber es funktioniert jetzt für mich für S4.
Vorher
Es sieht so aus, als würden Slots der S4-Klasse unter Roxygen2 Version 3.0+ vollständig unterstützt:
http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/
„dokumentieren Sie Ihre S4 Klassen, S4 Methoden und RC Klassen mit roxygen2 - Sie können sicher Abhilfen entfernen , dass verwendet
@alias
und@usage
, und verlassen sich einfach auf roxygen2 , das Richtige zu tun.“quelle