Roxygen2 - how to properly document S3 methods
I've read the开发者_开发技巧 Roxygen2 PDF and this site, and I'm lost on the difference between @method @S3method @export and how to use these to properly document S3 methods. I worked up the follow example for discussion:
- How would I properly document these?
- How do I emulate documentation of ?print and other generic functions that show the use cases for all class-specific implimentations (i.e. the way ?print shows usage for 'factor', 'table','function')
- From the wiki page: "All exported methods need the @S3method tag. It has the same format as @method. This exports the method, not the function - i.e. generic(myobject) will work, but generic.mymethod(myobject) will not." I can't interpret this. This seems to say that function/method calls won't work properly if the tags are improperly specified? What specifically will break?
MyHappyFunction = function( x , ... )
{
UseMethod( "MyHappyFunction" )
}
MyHappyFunction.lm = function( x , ... )
{
# do some magic
}
As of roxygen2 >3.0.0, you only need @export
:
#' 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)
#' @export
MyHappyFunction <- function(x, ...){
UseMethod("MyHappyFunction")
}
#' @rdname MyHappyFunction
#' @export
MyHappyFunction.lm = function(x, ...) {
# do some magic
}
#' @rdname MyHappyFunction
#' @export
MyHappyFunction.default = function(x, ...) {
# do some magic
}
But since you're not actually documenting the methods, the following is sufficient:
#' 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)
#' @export
MyHappyFunction <- function(x, ...){
UseMethod("MyHappyFunction")
}
#' @export
MyHappyFunction.lm = function(x, ...) {
# do some magic
}
#' @export
MyHappyFunction.default = function(x, ...) {
# do some magic
}
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
."
精彩评论