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 @slotTags 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 @slotin 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, \itemAnsatz 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 @importTag 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 @paramdem dasselbe erreicht werden kann.

Ich leihe mir diese Frage aus einem Beitrag aus, den ich auf der roxygen2Entwicklungsseite von Github verfasst habe .

Aktualisierte Antwort für Roxygen2 5.0.1, aktuell ab 6.0.1

Für S4 ist es jetzt die beste Vorgehensweise, mit dem @slotTag 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, @exportClassist nur in einigen Fällen die allgemeine Methode zum Exportieren einer Funktion @exportjetzt 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:

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

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

Die von Full Decent bereitgestellte Lösung ist in Ordnung, wenn Sie Slots in den Rd-Dateien selbst dokumentieren. Bei der Verwendung roxygen2können Sie das Tag verwenden @section, um im Grunde dasselbe mit zu tun \describe. 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

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 @aliasund @usage, und verlassen sich einfach auf roxygen2 , das Richtige zu tun.“