22

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.)

Richie Cotton
  • 118,240
  • 47
  • 247
  • 360
  • 4
    I believe you just use `@export` with the full name of the function. It would be helpful to include a [reproducible example](http://stackoverflow.com/questions/5963269/how-to-make-a-great-r-reproducible-example) to test. – MrFlick Jul 06 '14 at 16:50
  • @MrFlick Thanks for the solution, and thanks for reminding me not to be lazy. – Richie Cotton Jul 07 '14 at 09:58

2 Answers2

22

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)
Richie Cotton
  • 118,240
  • 47
  • 247
  • 360
  • 4
    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. – Ken Williams Jan 08 '15 at 16:08
  • 7
    **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(...)`. – Jthorpe Mar 06 '15 at 20:48
  • 1
    @Jthorpe 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). – R Yoda Dec 24 '18 at 11:42
-1

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

Community
  • 1
  • 1
Dirk
  • 1,134
  • 2
  • 12
  • 21
  • 2
    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). – Richie Cotton Dec 14 '14 at 05:10