Exporting non-S3-methods with dots in the name using roxygen2 v4

Question

Since roxygen2 version 4.0.0, the @S3method tag has been deprecated in favour of using @export.

The package now tries to detect if a function is an S3 method, and automatically adds the line S3method(function,class) to the NAMESPACE file if it think it is one.

The problem is that if a function is not an S3 method but its name contains a . then roxygen sometimes makes a mistake and adds the line when it shouldn't.

Is there a way to tell roxygen that a function is not an S3 method?

---

As requested, here's a reproducible example.

I have a package that imports R.oo, with a function named check.arg.

library(roxygen2)
package.skeleton("test")
cat("Imports: R.oo\n", file = "test/DESCRIPTION", append = TRUE)
writeLines(
  "#' Check an argument 
#' 
#' Checks an argument.
#' @param ... Some arguments.
#' @return A value.
#' @export
check.arg <- function(...) 0",
  "test/R/check.arg.R"
)
roxygenise("test")

Now the namespace contains the line S3method(check,arg).

check is an S3 generic in R.oo, so roxygen is trying to be smart and guessing that I want check.arg to be an S3 method. Unfortunately, these functions are unrelated, so I don't.

(To preempt suggestions that I just rename check.arg: this is legacy code written by others, and I've created a checkArg replacement, but I need to leave check.arg as a deprecated function for compatibility.)

Jaw

I believe you just use @export with the full name of the function. It would be helpful to include a reproducible example to test. – Desrosiers

@Desrosiers Thanks for the solution, and thanks for reminding me not to be lazy. – Jaw

Answer 1

As Mr Flick commented, appending the full function name to the roxygen line works correctly. If I change the line to:

#' @export check.arg

then the NAMESPACE file contains:

export(check.arg)

Jaw

The other problem to take care of is the usage statement, which will say ## S3 method for class ’check’\n check(...) unless you fix it. One way is to just add a ##' @usage check.arg(x) directive, not sure if there's a better way. – Recognizance

Note that the above solution will get you a correct entry in your NAMESPACE file. However, to get the function documented correctly, you also need to add a @usage tag, otherwise the message ## S3 method for class 'arg' will appear just above the signature of your function in it's .Rd file and the signature in the help file will be check(...) and not check.arg(...). – Stith

@Stith Great note (would be worth an answer!). R CMD check may still complain with a warning like Found the following apparent S3 methods exported but not registered: and you have to rename the function then to for a successful submission at CRAN (they don't allow warnings). – Irrepressible

Answer 2

Use @method generic class and @export instead of @S3method. Take a look at this thread: S3 method help (roxygen2)

Transeunt

This question isn't about how to document S3 methods; it is about the opposite problem of documenting things that aren't S3 methods (but roxygen thinks that they are). – Jaw