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 @slot
tag dalam deskripsi awal roxygen.
Pos milis R-forge 2008
nampaknya mengindikasikan bahwa ini sudah mati, dan tidak ada dukungan untuk @slot
di 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
, \item
pendekatan 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 @import
tag.
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 roxygen2
halaman pengembangan di github .
@slot
mungkin yang Anda inginkan untuk jangka panjang, tetapi harus diimplementasikan dulu ...setClass
pernyataan daripadasetMethod
. Membuat perubahan begitu@slot
diterapkan tidak akan terlalu menyakitkan.Jawaban:
Jawaban yang diperbarui untuk Roxygen2 5.0.1, saat ini pada 6.0.1
Untuk S4, praktik terbaik sekarang adalah mendokumentasikan menggunakan
@slot
tag:Pada sidenote,
@exportClass
hanya diperlukan dalam beberapa kasus, cara umum untuk mengekspor fungsi sedang digunakan@export
sekarang. 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:
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
sumber
@slot
solusi). Saya belum sempat mencobanya, menunggu (mungkin malas) untuk@slot
solusi yang tertunda ini . Saya tahu itu bukan bagaimana pertanyaan diajukan, tetapi berdasarkan komentar (termasuk @ hadley) sepertinya@slot
adalah jawaban "nyata". Saya setuju dengan penilaian Anda bahwa daftar terperinci (seperti dalam pertanyaan saya) adalah praktik terbaik saat ini, meskipun mudah-mudahan segera diganti.Solusi yang diberikan oleh Full Layak tidak masalah jika Anda mendokumentasikan slot dalam file Rd itu sendiri. Saat menggunakan
roxygen2
, Anda dapat menggunakan tag@section
untuk melakukan hal yang sama pada dasarnya\describe
. Sebuah contoh:sumber
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
@alias
dan@usage
, dan hanya mengandalkan roxygen2 untuk melakukan hal yang benar."sumber