roxygen (2)로 클래스를 문서화하는 경우 제목과 설명 / 세부 사항을 지정하는 것은 함수, 메서드, 데이터 등과 동일하게 나타납니다. 그러나 슬롯과 상속은 고유 한 종류의 동물입니다. roxygen2에서 S4 클래스를 문서화하기위한 현재 또는 계획된 모범 사례는 무엇입니까?
실사 :
@slot
roxygen의 초기 설명에서 태그에 대한 언급을 발견 했습니다.
2008 R- 포지 메일 링리스트 포스트
는 이것이 죽었고 @slot
roxygen에 대한 지원이 없음을 나타냅니다 .
이것이 roxygen2의 사실입니까? 앞서 언급 한 게시물은 사용자가 LaTeX 마크 업을 사용하여 항목별로 목록을 작성해야한다고 제안합니다. 예를 들어 클래스를 확장하는 새로운 S4 클래스 "character"
는 다음과 같이 코딩되고 문서화됩니다.
#' 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"
)
그러나이 작동하지만,이 \describe
, \item
슬롯을 문서화하기위한 접근 방법은 점에서 더 없다, roxygen (2)의 나머지 부분과 일치하지 않는 것 같다 @
-delimited 태그와 슬롯에서 어떤 반대와 미등록 갈 수있다 roxygenize()
. 또한 정의되는 클래스의 상속을 문서화하는 일관된 방법에 대해서는 아무 것도 말하지 않습니다. @import
태그를 사용하여 종속성이 여전히 정상적으로 작동한다고 생각합니다 (특정 슬롯이 다른 패키지의 비 기본 클래스가 필요한 경우) .
요약하면, roxygen (2) 슬롯에 대한 현재 모범 사례는 무엇입니까?
현재 고려해야 할 세 가지 옵션이있는 것 같습니다.
- A-항목 별 목록 (위의 예와 같이).
- B
@slot
-…하지만 여분의 태그 / 구현으로 놓쳤습니다. 위의 예제에서 항목 별 목록의 대체로 포함 된 버전에서 roxygen / roxygen2로 @slot을 사용할 수 없었습니다. 다시, 위의 예는 roxygen (2)에서 작동합니다.- C-
@param
같은 것을 달성 하는 슬롯을 지정하기위한 대체 태그 .
github 의 roxygen2
개발 페이지에 게시 한 게시물 에서이 질문을 빌리거나 연장하고 있습니다.
답변
6.0.1 현재 Roxygen2 5.0.1에 대한 답변이 업데이트되었습니다.
S4의 경우 이제 모범 사례는 @slot
태그를 사용하여 문서화하는 것입니다 .
#' 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
참고로, @exportClass
일부 경우에만 필요하며, 함수를 내보내는 일반적인 방법은 @export
지금 사용하는 것입니다 . 다른 패키지에서 클래스를 확장 할 수 없도록하려면 클래스를 내보낼 필요가 없습니다.
http://r-pkgs.had.co.nz/namespace.html#exports 도 참조하십시오.
Roygen2 3.0.0에 대한 답변이 5.0.1 현재 업데이트되었습니다.
S4의 경우 모범 사례는 다음 형식의 문서입니다.
#' \section{Slots}{
#' \describe{
#' \item{\code{a}:}{Object of class \code{"numeric"}.}
#' \item{\code{b}:}{Object of class \code{"character"}.}
#' }
#' }
이것은 객체 내부의 목록으로 슬롯의 내부 표현과 일치합니다. 지적한 바와 같이,이 구문은 다른 라인과 다르므로 미래에 상속에 대한 지식을 통합하지만 오늘날에는 존재하지 않는보다 강력한 솔루션을 기대할 수 있습니다.
@Brian Diggs가 지적 했듯이이 기능은 3.0.0으로 가져 왔습니다. https://github.com/klutometis/roxygen/pull/85
답변
Rd 파일 자체에 슬롯을 문서화하려는 경우 Full Decent에서 제공하는 솔루션은 정상입니다. 사용하는 경우 roxygen2
, 당신은 태그를 사용할 수 @section
와 기본적으로 동일 할 \describe
. 예를 들면 :
#' 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 이상 및 Hadley의 최신 문서 :
http://r-pkgs.had.co.nz/man.html#man-classes
RC에서는 아직 시도하지 않았지만 지금은 S4에서 작동합니다.
이전
Roxygen2 버전 3.0 이상에서는 S4 클래스 슬롯이 완전히 지원되는 것 같습니다.
http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/
“roxygen2와 S4 클래스, S4 방법과 RC 클래스를 문서화 – 안전하게 사용하는 것이 해결 방법을 제거 할 수 있습니다 @alias
및 @usage
, 단순히 옳은 일을 roxygen2에 의존하고 있습니다.”