Sam Firke Sam Firke - 1 month ago 5
R Question

S3 generic method not appearing in package manual

In my R package, a few functions are omitted from the package manual .pdf file - and they are all S3 methods where several functions are documented together. All other "normal" functions appear correctly, so I suspect I'm not documenting the S3 methods correctly.

I want an entry for

myfun
to appear in the manual. Right now, the function is missing from the .pdf manual entirely, though it can still be called correctly and its help page referenced with
?myfun
. Are my Roxygen2 keywords wrong?

#' @export
myfun <- function(...) UseMethod("myfun")

#' @inheritParams myfun
#' @describeIn myfun Create a frequency table from a vector.
#' @export
#' @keywords internal

myfun.default <- function(vec, sort = FALSE, show_na = TRUE, ...) {
...
}

#' @inheritParams myfun.default
#' @describeIn myfun Create a frequency table from a data.frame,
#' supplying the unquoted name of the column to tabulate.
#' @export
#' @keywords internal
tabyl.data.frame <- function(.data, ...){
...
}


(I omitted the
@title, @description, @param, @return, @examples
lines to keep this question shorter but can edit them in if relevant).

The generic methods are exporting as intended, so that the user only sees
myfun()
and not
myfun.default()
or
myfun.data.frame()
, unless they use the triple colon
:::
. I'd like to retain that behavior, so the user just calls
myfun
, while also having an entry for
myfun
in the package manual.

Answer

I removed @keywords internal in the two myfun. methods and that did it: myfun appears in the package's manual. I also switched to @rdname myfun instead of @describeIn myfun, to eliminate the section "Methods (by class):" in the function's documentation.

What made this hard to isolate was that if I run devtools::document() and then don't restart the session, the methods myfun.data.frame and myfun.default are visible in RStudio's autocomplete and can be called directly. They are not supposed to be accessible to the user, and I thought my Roxygen2 documentation was to blame.

In fact, all I had to do was remove @keywords internal.

The methods myfun.data.frame and myfun.default do appear in the autocomplete after typing ?, e.g., ?myfun.default, but I think there's no way around that (and it directs to the single help page for all three myfun functions, anyway). This is standard. For example, ?print.aov is a visible help file while print.aov() cannot be called directly.