r - Roxygen2 - 如何正确记录 S3 方法

Question

我已经阅读了 Roxygen2 PDF 和这个站点，我对 @method @S3method @export 之间的区别以及如何使用它们来正确记录 S3 方法感到迷茫。我制定了以下示例进行讨论：

1. 我将如何正确记录这些？
   
   

2. 如何模拟 ?print 和其他通用函数的文档，这些函数显示所有特定于类的实现的用例（即 ?print 显示“因子”、“表”、“函数”的用法的方式）
   
   

3. 从 wiki 页面：“所有导出的方法都需要 @S3method 标记。它与@method 具有相同的格式。这会导出方法，而不是函数 - 即 generic(myobject) 将起作用，但 generic.mymethod(myobject) 不会。”
   我无法解释这一点。这似乎是说如果标签指定不正确，函数/方法调用将无法正常工作？具体会破什么？

   MyHappyFunction = function( x , ... ) { UseMethod( "MyHappyFunction" ) }

   MyHappyFunction.lm = 函数( x , ... ) {

   做一些魔术

   }

Answer 1

从 roxygen2 >3.0.0 开始，您只需要@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
}

但由于您实际上并未记录方法，因此以下内容就足够了：

#' 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
}

Answer 2

该@method标签在 Rd 文件的 \usage 字段中生成 \method 条目。

该@S3method标记在 NAMESPACE 文件中生成 S3method() 条目。

该@export标记在 NAMESPACE 文件中生成 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)
#'
#' @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 从维基页面...

我猜它的意思是“你不写@S3method generic mymethod myobject”。