Identification of the Rd file name when extending the S4 method of another package

Question

Actual question

Avoiding Rd File Name Conflicts When

• S4 generic and its method need not be defined in one package (a package containing (some)) the custom method (s) depends on a package containing a common one) and
• using roxygenize() from the roxygen2 package to create real Rd files?

I'm not sure if this is a roxygen2 problem or a general problem when the general one and their methods are scattered across packages (which IMHO as a whole is definitely a realistic scenario to use if you follow a modular programming style).

What is the recommended way to deal with these situations?

Illustration

In pkga package

Suppose that in the pkga package you defined the general foo method and that you provided the corresponding roxygen code that roxygenize() chooses to create the Rd file:

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

When roxygenizing() your package, a file called foo-methods.Rd is created in the man subdirectory, which serves as the Rd reference file for all methods that can be created for this generic method. So far, so good. If all the methods of this pedigree are also part of your package, all is well. For example, this roadcode will add documentation to foo-methods.Rd for the 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)) ) 

However, if the pkga package provides a common package for foo and you decide in some other package (say pkgb ) to add a foo method for x of the character class, then the R CMD check will tell you that there is a name clash regarding the Rd and / or file names aliases (since the Rd foo-methods.Rd file already exists in the pkga file):

In pkgb package

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

To be more precise, this is an error that was sent / written to 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' 

Due dilligence

I tried changing the values ​​for @rdname and @aliases to foo_pkgb* (instead of foo* ), but \title and \name are still set to foo when rogening and therefore the error remains. Any ideas besides manually editing the Rd files generated by roxygenize() ?

---

EDIT 2012-12-01

In the light of the beginning of generosity, the real question may get a slightly wider taste:

How can we implement some “inter-package” checking for Rd files and / or how can we consolidate S4 help files scattered across packages into a single Rd file to represent a single source link to an end user?

Answer 1

The main question - really "oxygenate" - only. That is why I have never seen a problem.

Despite the fact that there are reasonable reasons for the approach based on the oxygenation development of the package, I still see a very good reason not :

Request for a much lower degree of oxygenation

As a result, the help pages tend to look extremely boring, not only the automatically generated * .Rd files, but also the rendering result. For example.

• examples are often minimal, do not contain comments, often not very well formatted (using space, / new lines / ..)
• Math questions are rarely explained with \ eqn {} or \ deqn {}
• \ describe {..} and similar higher-level formatting is rarely used

Why? Because

1) reading and editing roxygen comments is much more "cumbersome" or at least visually unacceptable than reading and editing * .Rd files in ESS or Rstudio or (another development environment in which * .Rd support is built in)

2) If you use this documentation

- this is what is automatically generated at the end of your package / check build

you usually tend not to see well-written R documentation as something important (but rather your R code, for which all documents are just a comment :-)

The result of all this: people prefer to write documentation about their functions in vignettes or even blogs, github gists, youtube videos, or ... where it is very good at the time of creation, but is largely separated from the code and has become obsolete and fading ( and therefore, using Google misled your useRs) -> The original motivation of roxygen to have the code and documentation in the same place is completely defeated.

I like roxygen and use it extensively when creating a new function ... and I save and maintain it until my function is in a package, or exported. Once I decided to export it, I run (equivalent to ESS) roxygenize () once and since then take a small burden of supporting the * .Rd file, which is well formatted, contains its own comments (for me as an author), has many good examples , has its own version control (git / svn / ...) history, etc.

Answer 2

I managed to create NAMESPACE and * .Rd files for S4 methods for generics defined in a different package than mine.

It took me the following steps:

• Manually create NAMESPACE as a workaround for the well-known error roxygen2 .

  Writing NAMESPACE manually is not so difficult!

  Disable NAMESPACE generation with roxygen2 in RStudio:

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

• Import a package containing a generic type, and export S4 methods using exportMethods methods .

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

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

It makes me work for me.