Đối với các lớp tài liệu với roxygen (2), việc chỉ định một tiêu đề và mô tả / chi tiết dường như giống với các hàm, phương thức, dữ liệu, v.v. Tuy nhiên, khe và thừa kế là loại động vật riêng của chúng. Cách thực hành tốt nhất - hiện tại hoặc theo kế hoạch - để ghi lại các lớp S4 trong roxygen2 là gì?

Do siêng năng:

Tôi thấy đề cập đến một @slotthẻ trong các mô tả ban đầu của roxygen. Một bài đăng danh sách gửi thư R-forge năm 2008 dường như chỉ ra rằng điều này đã chết và không có hỗ trợ nào @slottrong roxygen:

Điều này có đúng với roxygen2 không? Bài đăng được đề cập trước đó cho thấy người dùng nên tạo danh sách ghi thành từng mục của riêng họ với đánh dấu LaTeX. Ví dụ, một lớp S4 mới mở rộng "character"lớp sẽ được mã hóa và ghi lại như sau:

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

Tuy nhiên, mặc dù điều này hoạt động, \describenhưng \itemcách tiếp cận này để ghi lại các vị trí có vẻ không phù hợp với phần còn lại của roxygen (2), trong đó không có @thẻ và giới hạn nào có thể không được ghi nhận mà không bị phản đối roxygenize(). Nó cũng không nói gì về một cách nhất quán để ghi lại sự kế thừa của lớp được định nghĩa. Tôi tưởng tượng sự phụ thuộc nói chung vẫn hoạt động tốt (nếu một vị trí cụ thể yêu cầu lớp không cơ sở từ gói khác) sử dụng @importthẻ.

Vì vậy, để tóm tắt, thực tiễn tốt nhất hiện nay cho các khe roxygen (2) là gì?

Có vẻ như có ba lựa chọn để xem xét tại thời điểm này:

• A - Danh sách cụ thể hóa (như ví dụ ở trên).
• B - @slot... nhưng với các thẻ bổ sung / triển khai tôi đã bỏ lỡ. Tôi đã không thể để @slot hoạt động với roxygen / roxygen2 trong các phiên bản mà nó được đưa vào để thay thế cho danh sách được ghi thành từng mục trong ví dụ trên. Một lần nữa, ví dụ trên không hoạt động với roxygen (2).
• C - Một số thẻ thay thế để chỉ định vị trí, như @param, sẽ hoàn thành điều tương tự.

Tôi đang mượn / mở rộng câu hỏi này từ một bài đăng tôi đã viết cho roxygen2trang phát triển trên github .

Câu trả lời được cập nhật cho Roxygen2 5.0.1, hiện tại kể từ 6.0.1

Đối với S4, cách tốt nhất bây giờ là ghi lại bằng @slotthẻ:

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

Trên một sidenote, @exportClasschỉ cần thiết trong một số trường hợp, cách chung để xuất một hàm hiện đang sử dụng @export. Bạn cũng không phải xuất một lớp, trừ khi bạn muốn các gói khác có thể mở rộng lớp.

Xem thêm http://r-pkgs.had.co.nz/namespace.html#exports

Câu trả lời được cập nhật cho Roygen2 3.0.0, hiện tại kể từ 5.0.1.

Đối với S4, cách thực hành tốt nhất là tài liệu theo mẫu:

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

Điều này phù hợp với biểu diễn bên trong của các vị trí dưới dạng một danh sách bên trong đối tượng. Như bạn chỉ ra, cú pháp này khác với các dòng khác và chúng tôi có thể hy vọng một giải pháp mạnh mẽ hơn trong tương lai kết hợp kiến ​​thức về thừa kế - nhưng ngày nay điều đó không tồn tại.

Như @Brian Diggs đã chỉ ra, tính năng này đã được kéo vào 3.0.0, thảo luận thêm tại https://github.com/klutometis/roxygen/pull/85

Giải pháp được cung cấp bởi Full Decent là OK nếu bạn sử dụng tài liệu cho các vị trí trong các tệp tin của chính nó. Khi sử dụng roxygen2, bạn có thể sử dụng thẻ @sectionđể thực hiện tương tự như vậy \describe. Một ví dụ:

#' 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 + và tài liệu mới nhất của Hadley để làm điều này:

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

Tôi chưa thử nó cho RC, nhưng nó hoạt động với tôi cho S4 bây giờ.

Trước đây

Có vẻ như các khe lớp S4 được hỗ trợ đầy đủ theo Roxygen2 phiên bản 3.0+:

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

"tài liệu lớp S4 của bạn, phương pháp S4 và các lớp RC với roxygen2 - bạn có thể loại bỏ một cách an toàn cách giải quyết mà sử dụng @aliasvà @usage, và chỉ đơn giản dựa vào roxygen2 để làm điều đúng đắn."