Roxygen2를 사용하여 S4 클래스 슬롯을 올바르게 문서화하는 방법은 무엇입니까?

Roxygen2를 사용하여 S4 클래스 슬롯을 올바르게 문서화하는 방법은 무엇입니까?

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

실사:

에 대한 언급을 찾았습니다.@slotroxygen에 대한 초기 설명의 태그.2008년 R-forge 메일 목록 게시물은 이것이 사망했음을 나타내는 것으로 보이며, 이에 대한 지원은 없습니다.@slot록시겐:

이것이 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슬롯을 문서화하는 접근 방식은 존재하지 않는다는 점에서 나머지 록시겐(2)과 일치하지 않는 것 같습니다.@-의 이의 없이 허가된 태그와 슬롯이 문서화되지 않은 상태로 진행될 수 있습니다.roxygenize()또한 정의되는 클래스의 상속을 문서화하는 일관된 방법에 대해서도 설명하지 않습니다.나는 의존성이 여전히 일반적으로 잘 작동한다고 생각합니다(특정 슬롯에 다른 패키지의 기본 클래스가 필요한 경우).@import꼬리표를 달다

요약하자면, 록시겐(2) 슬롯에 대한 현재 모범 사례는 무엇입니까?

현재 고려해야 할 세 가지 옵션이 있는 것 같습니다.

• A - 항목별 목록(위의 예).
• B --@slot추가 태그/구현을 놓쳤습니다.위의 예에서 항목화된 목록의 대체품으로 포함된 버전에서 @slot을 roxygen/roxygen2로 작업할 수 없었습니다.다시 말하지만, 위의 예는 Roxygen(2)과 함께 작동합니다.
• C - 슬롯 지정을 위한 대체 태그입니다.@param그것은 같은 일을 이룰 것입니다.

제가 만든 게시물에서 이 질문을 빌리고 있습니다.roxygen2github의 개발 페이지.

Roxygen25.0.1에 대한 답변 업데이트, 7.2.0 기준

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+ 및 해들리의 최근 문서는 다음과 같습니다.

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

RC용으로 아직 시도해본 적은 없지만, 지금은 S4용으로 가능합니다.

이전에.

S4 클래스 슬롯은 Roxygen2 버전 3.0+에서 완전히 지원되는 것 같습니다.

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

"S4 , 및 RC 클래스를 . "roxygen2"를 방법을 안전하게 할 수 사용된 해결 방법을 안전하게 제거할 수 있습니다.@alias그리고.@usage그리고 단순히 올바른 일을 하기 위해 roxygen2에 의존합니다."

언급URL : https://stackoverflow.com/questions/7368262/how-to-properly-document-s4-class-slots-using-roxygen2