Documenting R.oo classes/methods with Roxygen

Question

Could someone point me to a good example of documenting R.oo classes/methods with Roxygen? In R.oo, classes/methods are created by calls to setConstructorS3() and setMethodS3(), so there is no function to document per-se. Do you simply create standard Roxygen function documentation, but place it on top of a NULL statement?

Answer 1

After some trial & error, here's what I came up with. This solution ensures that all objects are exported properly, that R CMD build/check does not puke, that there is no redundant documentation, and that examples will execute. Note that the solution won't work if @export is replaced with @method/@S3method. Theoretically that should work, but it didn't for me. Someone have a better solution?

#' Title.  More Info.
#'
#' @param someParam  Param info.
#'
#' @name     MyMethod
#' @export   MyMethod
NULL
#' @rdname   MyMethod
#' @name     MyMethod.ClassName
#' @export   MyMethod.ClassName
setMethodS3( "MyMethod" , "ClassName" , appendVarArgs = FALSE , 
function( this , someParam ) { ... } )

Answer 2

I think,

1. @usage are needed.
2. A dot-dot-dot argument is needed in the MyMethod.ClassName function for S3 generic/method consistency.
3. Not #' @export MyMethod.ClassName but rather #' @S3method MyMethod ClassName?

An example code:

#' Title.  More Info.
#'
#' @usage MyMethod(...)
#' @param this this.
#' @param someParam Param info.
#' @param ... other arguments.
#'
#' @rdname   MyMethod
#' @export   MyMethod
#' @name     MyMethod
NULL

#' @usage \method{MyMethod}{ClassName}(this, someParam, ...)
#' @return MyMethod.ClassName:
#' \code{NULL}
#'
#' @rdname   MyMethod
#' @S3method MyMethod ClassName
#' @name     MyMethod.ClassName
setMethodS3("MyMethod", "ClassName", appendVarArgs = FALSE, 
function(this, someParam, ...) {
  NULL
})