다른 패키지의 S4 메서드를 확장 할 때 Rd 파일 이름 충돌

다른 패키지의 S4 메서드를 확장 할 때 Rd 파일 이름 충돌

---

실제 질문

Rd 파일 이름 충돌을 피하려면 어떻게해야합니까?

1. S4 일반 및 방법 (들)이되어 있지 반드시 모두 동일한 패키지에 정의 (패키지 (의 일부)를 지정 방법 (들)을 함유하는 일반을 포함하는 패키지에 의존) 및
2. 사용하여 roxygenize()패키지에서 roxygen2은 실제 RD 파일을 생성하려면?

roxygen2제네릭과 그 방법이 패키지에 흩어져있을 때 이것이 문제인지 또는 일반적인 문제 인지 확실하지 않습니다 (일반적으로 IMHO는 모듈 식 프로그래밍 스타일을 따르는 경우 현실적인 사용 사례 시나리오입니다).

이러한 상황을 처리하는 데 권장되는 방법은 무엇입니까?

삽화

패키지 pkga

패키지 pkga에서 일반 메서드를 정의 하고 Rd 파일을 생성하기 위해 선택 foo하는 각각의 roxygen 코드를 제공했다고 가정 roxygenize()합니다.

#' Test function
#' 
#' Test function.
#' 
#' @param ... Further arguments.
#' @author Janko Thyson \email{janko.thyson@@rappster.de}
#' @example inst/examples/foo.R
#' @docType methods
#' @rdname foo-methods
#' @export

setGeneric(
    name="foo",
    signature=c("x"),
    def=function(
         x,  
        ...
    ) {
    standardGeneric("xFoo")       
    }
)

때 roxygenizing()패키지라는 파일이 foo-methods.Rd에서 생성 man이 일반적인 방법에 대해 생성 할 수있는 모든 방법에 대한 기준 RD 파일의 역할을 하위 디렉토리. 여태까지는 그런대로 잘됐다. 이 제네릭에 대한 모든 메서드가 패키지의 일부이면 모든 것이 좋습니다. 예를 들어,이 roxygen 코드는 반드시 문서가 추가되었는지 확인 할 foo-methods.Rd에 대한 ANY의 -method foo:

#' @param x \code{ANY}.
#' @return \code{TRUE}.
#' @rdname foo-methods
#' @aliases foo,ANY-method
#' @export

setMethod(
    f="foo", 
    signature=signature(x="ANY"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(TRUE)
    }, options=list(suppressAll=TRUE))
)

패키지는 그러나 pkga에 대한 일반적인 제공 foo하고 다른 패키지 (말에 결정 pkgb추가) foo에 대한 -method를 x클래스의 복지 character, 다음 R CMD checkRD 파일 이름 및 / 또는 별칭에 대한 이름 충돌이 있음 (같은 당신을 말할 것이다 )에 이미 Rd 파일 foo-methods.Rd이 pkga있습니다.

패키지 pkgb

#' @param x \code{character}.
#' @return \code{character}.
#' @rdname foo-methods
#' @aliases foo,character-method
#' @export

setMethod(
    f="foo", 
    signature=signature(x="character"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(x)
    }, options=list(suppressAll=TRUE))
)

더 정확하게 말하면 이것은 파일에 던지거나 쓰는 오류입니다. 00install.out

Error : Q:/pkgb/man/foo-methods.Rd: Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'pkgb'

때문에 dilligence

나는 값을 변경하려 @rdname과 @aliases에 foo_pkgb*(대신 foo*) 만 \title하고 \name아직 설정되어 foo, 따라서 오류 남아 roxygenizing 때. 에 의해 생성 된 Rd 파일을 수동으로 편집하는 것 외에 다른 아이디어 가 roxygenize()있습니까?

---

2012-12-01 수정

In light of starting the bounty, the actual question might get a slightly broader flavor:

How can we implement some sort of an "inter-package" check with respect to Rd files and/or how can we consolidate S4 method help files scattered across packages into one single Rd file in order to present a single source of reference to the end-user?

---

The basic question is indeed "roxygenize"-only. That's why I never had seen the problem.

While there are good reasons for the roxygenizing approach of package development, I still see a very good reason not to go there:

Plea for much less extreme roxygenation

The resulting help pages tend to look extremely boring, not only the auto generated *.Rd files but also the rendered result. E.g.

1. examples are often minimal, do not contain comments, are often not well formatted (using space, / new lines /..)
2. Mathematical issues are rarely explained via \eqn{} or \deqn{}
3. \describe{ .. } and similar higher level formatting is rarely used

Why is that? Because

1) reading and editing roxygen comments is so much more "cumbersome" or at least visually unrewarding than reading and editing *.Rd files in ESS or Rstudio or (other IDE that has *.Rd support built in)

2) If you are used that documentation

is the thing that's automatically generated at the end of your package building/checking

you typically tend to not considerung well written R documentation as something important (but rather your R code, to which all the docs is just a comment :-)

The result of all that: People prefer writing documentation about their functions in vignettes or even blogs, github gists, youtube videos, or ... where it is very nice at the time of authoring, but is pretty much detached from the code and bound to get outdated and withering (and hence, via Google search misleading your useRs) --> The original motivation of roxygen of having code and documentation in the same place is entirely defeated.

I like roxygen and use it extensively at the time I create a new function... and I keep and maintain it as long as my function is not in a package, or is not exported. Once I decide to export it, I run (the ESS equivalent of) roxygenize() once and from then on take the small extra burden of maintaining a *.Rd file that is well formatted, contains its own comments (for me as author), has many nice examples, has its own revision control (git / svn / ...) history, etc.

---

I managed to generate NAMESPACE and *.Rd files for S4 methods for generics defined in another package than mine.

It took me the following steps:

1. Create NAMESPACE by hand as a workaround to a known roxygen2 bug.

   Writing a NAMESPACE by hand is not so difficult at all!

   Switch off NAMESPACE generation by roxygen2 in RStudio:

   Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.
   

2. import the package containing the generic and export the S4 methods using exportMethods.

3. Write separate roxygen2 documentation for each of the S4 methods. Do not combine roxygen2 documentation (as I generally do for different methods of the same generic).

4. Add explicit roxygen tags @title and @description to the roxygen documentation of the S4 methods. Write @description explicitly, even if its value is identical as @title.

That makes it work for me.

참고URL : https://stackoverflow.com/questions/13137912/rd-file-name-conflict-when-extending-a-s4-method-of-some-other-package