How to document functions that call the same function but have different parameters?

Question

I'm writing a package that has an internal function that several other exported functions use, but the exported functions all have different parameters.

Here is a simplification of what I mean:

general <- function(...) {
  # do something based on which function was called
}
one <- general
two <- general

I know it might seem weird, but all the functions that are aliased to general use the exact same code but they have different parameters. So I might call one(id = "foo") or two(class = "bar").

My question is how do I document these functions with roxygen in a way that R CMD check won't complain?

I want to document each function with its proper parameters, so this was what I was hoping to be able to use:

general <- function(...) {
  # do something based on which function was called
}
#' @param id The id
#' @export
one <- general
#' @param class The class
#' @export
two <- general

But then I get WARNINGs when I check my package such as

* checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'one'
  '...'
Documented arguments not in \usage in documentation object 'one':
  'id'

And similar warnings for the two function.

I tried editing the .Rd files by hand to change

\usage{ one(...) }

Into

\usage{ one(id) }

To try to fix this WARNING, but when I run the check it seems to be creating the documentation again and overwriting my change.

Is there a workaround for this?

Thanks

Thomas · Answer 1 · 2015-04-04T21:09:51.547

The idea of having aliases that are actually all just the same function seems confusing and there will not be a way to produce standard R documentation that passes R CMD check in this arrangement.

A better approach is to write functions one and two as wrappers around general that can pass arguments to it, rather than as aliases. This way you can give them actual arguments, that you can document using the standard Rd markup (or roxygen, if that's how you produce your documentation). From the perspective of the end-user, this will be much clearer and should be no more difficult for you to design as the developer.

EDIT: Based on your comment, this could work as follows:

general <- function(..., from) {
    if(from == "one") {
        # do stuff
    } else if (from == "two") {
        # do other stuff
    }
}

one <- function(...) {
    general(..., from = "one")
}

two <- function(...) {
    general(..., from = "two")
}

This way you can know which function was originally called without relying on match.call, which seems really dangerous, and still be able to document the functions one and two in a way that is complete and passes R CMD check.

Thank you. I did try making the exported functions wrappers that simply call `general`, but then I lose the information of what the original function that was called was. Inside `general` I use `match.call()[1]` to know what function was originally called, but if I use a wrapper it will not work. I know it seems confusing and non-ideal but I really think that it's the best and simplest approach for my application. I was hoping you wouldn't say "there will not be a way", that was my biggest fear :) — DeanAttali, Apr 04 '15 at 21:00

How to document functions that call the same function but have different parameters?

1 Answers1