Wie dokumentiere ich Slots der S4-Klasse mit Roxygen2 richtig?
Frage
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:
In frühen Beschreibungen von Sauerstoff wurde ein @slot
-Tag erwähnt.
Ein Beitrag zur R-Forge-Mailingliste 2008
scheint darauf hinzudeuten, dass dies tot ist,
und es gibt keine Unterstützung für @slot
in roxygen:
Zusammenfassend lässt sich sagen, was ist die derzeitige Best Practice für Roxygen (2) -Slots?
Im Moment scheinen drei Optionen in Betracht zu ziehen:
- A - Auflistung (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 wurde als Ersatz für die detaillierte Liste im Beispiel aufgenommen über. Auch hier funktioniert das obige Beispiel mit Sauerstoff (2).- C - Ein alternatives Tag zum Festlegen von Slots, wie z. B.
@param
, mit dem dasselbe erreicht werden kann.Ich leihe mir diese Frage aus einem Beitrag aus, den ich auf der
roxygen2
-Entwicklungsseite unter github verfasst habe .
Lösung 3
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 S4.
Zuvor
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 Problemumgehungen entfernen, die @alias
und @usage
verwendet haben, und sich einfach auf roxygen2 verlassen, um das Richtige zu tun."
Andere Tipps
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:
#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export
Nebenbei bemerkt ist @exportClass
nur in einigen Fällen erforderlich. Die allgemeine Methode zum Exportieren einer Funktion besteht jetzt in der Verwendung von @export
. 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 # exportiert
Aktualisierte Antwort für Roygen2 3.0.0, Stand 5.0.1.
Für S4 ist die Dokumentation die folgende Vorgehensweise:
#' \section{Slots}{
#' \describe{
#' \item{\code{a}:}{Object of class \code{"numeric"}.}
#' \item{\code{b}:}{Object of class \code{"character"}.}
#' }
#' }
Dies stimmt mit der internen Darstellung von Slots als Liste innerhalb des Objekts überein. Wie Sie hervorheben, unterscheidet sich diese Syntax von anderen Zeilen, und wir hoffen möglicherweise auf eine robustere Lösung für die Zukunft, die Vererbungskenntnisse beinhaltet - aber heute gibt es diese nicht.
Wie von @Brian Diggs hervorgehoben, wurde diese Funktion in 3.0.0 übernommen. Weitere Informationen finden Sie unter https://github.com/klutometis/roxygen/pull/85
Die von Full Decent bereitgestellte Lösung ist in Ordnung, wenn Sie Slots in den Rd-Dateien selbst dokumentieren.Wenn Sie roxygen2
verwenden, können Sie das Tag @section
verwenden, um im Grunde dasselbe mit \describe
zu tun.Ein Beispiel:
#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots:
#' \describe{
#' \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#' \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#' }
#'
#' @note You can still add notes
#' @name EXAMPLE
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys