How to Properly Document a S3 Method of a Generic from a Different Package, Using Roxygen

How to properly document a S3 method of a generic from a different package, using Roxygen?

As of roxygen2 > 3.0.0., you only need @export because roxygen can figure out that print.surveyor is an S3 method. This means that you now only need

#' Prints surveyor object.
#' 
#' @param x surveyor object
#' @param ... ignored
#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

However, in this case since the documentation isn't very useful, it'd probably better to just do:

#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

Roxygen2 - how to properly document S3 methods

The @method tag generates \method entries in the \usage field in Rd files.

The @S3method tag generates S3method() entries in the NAMESPACE file.

The @export tag generates export() entries in the NAMESPACE file.

Here is my example:

#' A description of MyHappyFunction
#'
#' A details of MyHappyFunction
#'
#' @title MyHappyFunction: The my happy function
#' @param x numeric number
#' @param ... other arguments
#' @examples
#' a <- 1
#' class(a) <- "lm"
#' MyHappyFunction(a)
#'
#' @rdname MyHappyFunction
#' @export MyHappyFunction
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#' @return \code{NULL}
#'
#' @rdname MyHappyFunction
#' @method MyHappyFunction lm
#' @S3method MyHappyFunction lm
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#' @return \code{NULL}
#'
#' @rdname MyHappyFunction
#' @method MyHappyFunction default
#' @S3method MyHappyFunction default
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

3 From the wiki page...

I guess that it means "you do not write @S3method generic mymethod myobject."

Roxygen documentation for existing generics

In the end, using explicit @aliases and @docType tags solved the issue for me. My documentation block now looks like this:

#' Show method for objects of class \code{myclass}.
#'
#' @docType methods
#' @name show-myclass
#' @rdname show-myclass
#' @aliases show-myclass show,myclass-method
#'
#' @param x A \code{myclass} object.
#'
#' @export

How do document an S3 generic for an R6 class?

As @Mikko suggested, I updated my version of roxygen (my original post is fairly old now). In 7.1.1, I no longer get the note. Thanks!

Roxygen thinks a function of mine is an S3 method, and so breaks upon installation of my package

Fixed it!

Using @export extract.sig.metadata instead of @export apparently tells roxygen that extract.sig.metadata is the entire function name, and this fixes the problem. In this particular case, I didn't have a generic extract function, but R.utils (a package that my package did not depend upon but was nevertheless loaded) did have an extract function.

Hope this helps anyone with the same problem in the future. Thanks!

P.S. Hadley suggests better naming practices, which I will attempt to follow in the future.

---

Related Topics