Untuk mendokumentasikan kelas dengan roxygen (2), menentukan judul dan deskripsi / perincian tampaknya sama dengan untuk fungsi, metode, data, dll. Namun, slot dan pewarisan adalah jenis binatang mereka sendiri. Apa praktik terbaik - saat ini atau yang direncanakan - untuk mendokumentasikan kelas S4 di roxygen2?

Uji kelayakan:

Saya menemukan menyebutkan @slottag dalam deskripsi awal roxygen. Pos milis R-forge 2008 nampaknya mengindikasikan bahwa ini sudah mati, dan tidak ada dukungan untuk @slotdi roxygen:

Apakah ini benar roxygen2? Posting yang disebutkan sebelumnya menyarankan pengguna sebagai gantinya harus membuat daftar terperinci dengan LaTeX markup. Misalnya kelas S4 baru yang memperluas "character"kelas akan dikodekan dan didokumentasikan seperti ini:

#' 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"
)

Namun, meskipun ini berhasil, ini \describe, \itempendekatan untuk mendokumentasikan slot tampaknya tidak konsisten dengan sisa roxygen (2), di mana tidak ada @tag dan slot yang dapat direvisi tanpa dokumen tanpa keberatan dari roxygenize(). Ia juga tidak mengatakan apa-apa tentang cara yang konsisten untuk mendokumentasikan warisan kelas yang sedang didefinisikan. Saya membayangkan ketergantungan umumnya masih berfungsi dengan baik (jika slot tertentu membutuhkan kelas non-basis dari paket lain) menggunakan @importtag.

Jadi, untuk meringkas, apa praktik terbaik saat ini untuk slot roxygen (2)?

Tampaknya ada tiga opsi untuk dipertimbangkan saat ini:

• A - Daftar terperinci (seperti contoh di atas).
• B - @slot... tetapi dengan tag / implementasi tambahan saya tidak terjawab. Saya tidak bisa mendapatkan @slot untuk bekerja dengan roxygen / roxygen2 dalam versi di mana ia dimasukkan sebagai pengganti daftar item pada contoh di atas. Sekali lagi, contoh di atas tidak bekerja dengan roxygen (2).
• C - Beberapa tag alternatif untuk menentukan slot, seperti @param, yang akan mencapai hal yang sama.

Saya meminjam / memperluas pertanyaan ini dari pos yang saya buat ke roxygen2halaman pengembangan di github .

Jawaban yang diperbarui untuk Roxygen2 5.0.1, saat ini pada 6.0.1

Untuk S4, praktik terbaik sekarang adalah mendokumentasikan menggunakan @slottag:

#' 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

Pada sidenote, @exportClasshanya diperlukan dalam beberapa kasus, cara umum untuk mengekspor fungsi sedang digunakan @exportsekarang. Anda juga tidak perlu mengekspor kelas, kecuali jika Anda ingin paket lain dapat memperluas kelas.

Lihat juga http://r-pkgs.had.co.nz/namespace.html#exports

Jawaban yang diperbarui untuk Roygen2 3.0.0, saat ini pada 5.0.1.

Untuk S4, praktik terbaik adalah dokumentasi dalam bentuk:

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

Ini konsisten dengan representasi internal slot sebagai daftar di dalam objek. Seperti yang Anda tunjukkan, sintaks ini berbeda dari baris lain, dan kami mungkin berharap untuk solusi yang lebih kuat di masa depan yang menggabungkan pengetahuan tentang pewarisan - tetapi hari ini tidak ada.

Seperti yang ditunjukkan oleh @Brian Diggs, fitur ini ditarik ke 3.0.0, diskusi lebih lanjut di https://github.com/klutometis/roxygen/pull/85

Solusi yang diberikan oleh Full Layak tidak masalah jika Anda mendokumentasikan slot dalam file Rd itu sendiri. Saat menggunakan roxygen2, Anda dapat menggunakan tag @sectionuntuk melakukan hal yang sama pada dasarnya \describe. Sebuah contoh:

#' 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 + dan dokumen Hadley terbaru untuk melakukan ini:

http://r-pkgs.had.co.nz/man.html#man-classes

Saya belum mencobanya untuk RC, tetapi bekerja untuk saya untuk S4 sekarang.

Sebelumnya

Sepertinya slot kelas S4 didukung sepenuhnya di bawah Roxygen2 versi 3.0+:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

"mendokumentasikan kelas S4 Anda, metode S4 dan kelas RC dengan roxygen2 - Anda dapat dengan aman menghapus workaround yang digunakan @aliasdan @usage, dan hanya mengandalkan roxygen2 untuk melakukan hal yang benar."