roxygen (2)로 클래스를 문서화하는 경우 제목과 설명 / 세부 사항을 지정하는 것은 함수, 메서드, 데이터 등과 동일하게 나타납니다. 그러나 슬롯과 상속은 고유 한 종류의 동물입니다. roxygen2에서 S4 클래스를 문서화하기위한 현재 또는 계획된 모범 사례는 무엇입니까?

실사 :

@slotroxygen의 초기 설명에서 태그에 대한 언급을 발견 했습니다. 2008 R- 포지 메일 링리스트 포스트 는 이것이 죽었고 @slotroxygen에 대한 지원이 없음을 나타냅니다 .

이것이 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에 의존하고 있습니다."