Documenting re-exported functions in an R package

Question

I'm in the process of splitting one of my R packages into two, since it incorporates two logically distinct sets of functionality, one of which is more general than the other. However, since the original package is reasonably popular, and is depended upon by at least one other package, I don't want to break compatibility.

R's namespace system provides a way to handle this, by importing the functions now in the split-off package (which is RNifti), and then re-exporting them from the downstream package (which is RNiftyReg). That way, third-party users and packages can load just RNiftyReg, and still see functions that now actually belong in RNifti. Moreover, the documentation for these functions still works, since the RNifti namespace is loaded along with RNiftyReg.

However, R CMD check complains, because the re-exported functions are not documented in RNiftyReg.

So my question is: what is the best practice in this scenario?

I seem to have three options, none of which appeal very much.

• Break existing code by requiring the new package, RNifti, to be loaded alongside RNiftyReg for all the previously-available functions to be available. Clearly that's undesirable.
• Duplicate all the documentation for these functions in the downstream package, RNiftyReg. That should keep everyone happy but is messy to maintain, and can easily get out of sync if the packages are not always updated together.
• Provide a single catch-all documentation page for all of these functions in RNiftyReg, pointing to the full documentation in RNifti. But that still needs to be kept in sync with respect to function arguments, and it requires users to use the ungainly ?RNifti::somefun syntax to see the "real" documentation.

Is there a way around this, or it simply unwise to re-export code like this?

Answer 1

From some further poking around, it looks like \docType{import}, added in R version 3.1.1, is the best available mechanism for handling this scenario (as noted in this roxygen2 issue). This seems to effectively behave like my third option above, but it has the advantage of not documenting the function arguments explicitly, so they don't have to be kept in sync.

It seems that roxygen2 syntax like

#' @export
RNifti::xform

generates the right form of .Rd file, and satisfies R CMD check. I wasn't using this particular syntax before, which is why the issue remained outstanding.

I've confirmed that this works with an unmodified third-party package, so it looks like the best bet.