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

Question

我已经阅读了Roxygen2 PDF和这个网站，但是我不知道@method @S3method @export之间的区别，也不知道如何使用它们来正确记录S3方法。 我已经准备了下面的示例以供讨论：

1. 我应该如何正确记录这些内容？
   
   
2. 如何模拟文档中 ?print 和其他通用函数的用例，这些用例显示所有特定类别实现的用法（即 ?print 显示 'factor'，'table'，'function' 的用法）？
   
   
3. 从维基页面得知：“所有导出的方法都需要 @S3method 标签。 它具有与 @method 相同的格式。 这将导出方法而不是函数-即 generic(myobject) 将起作用，但 generic.mymethod(myobject) 将无法正常工作。”
   我无法解释这个意思。这似乎表明如果标签未正确指定，则函数/方法调用将无法正常工作？ 具体来说，什么会出问题？

    MyHappyFunction = function( x , ... )
    {
        UseMethod( "MyHappyFunction" )
    }
    
    MyHappyFunction.lm = function( x , ... )
    {
      # do some magic
    }

- Suraj

---

几乎与https://dev59.com/6mw15IYBdhLWcg3wmMx9完全相同。 - Andrie

几乎 =) 填写三元组示例很好。 - Suraj

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
}

- hadley

---

这个例子非常简单明了，很可能适合放在这里：http://adv-r.had.co.nz/OO-essentials.html#s3 - Brandon Bertelsen

最新的r-devel是否存在这个问题？我正在使用roxygen2 4.1.1和开发R（rev 68657），有一个例子看起来与此非常相似，但是S3方法没有被正确识别... - Ben Bolker

@BenBolker 我也是，S3在命名空间中被导出()而不是S3'd。packageVersion("roxygen2") # [1] ‘4.1.1’ - tim

我和BenBolker以及tim遇到了相同的问题，后来在这里找到了解决方案：https://dev59.com/qInca4cB1Zd3GeqP8Dya#29639694。 - Julian Karch

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
}

从维基页面得知...

我猜这意味着 "你不需要编写@S3method generic mymethod myobject。"

- Triad sou.

---

正确。但是 @method + @export 相当于 @s3method。 - hadley

当我在roxygen（0.1-2）和roxygen2（2.1）中进行测试时，@method + @export与SFun28所说的@S3method是不等价的。@S3method没有生成\method条目。我认为在roxygen（0.1-2）和roxygen2（2.1）中都需要这两个标签。 - Triad sou.

+1. 已经正常运行并且之前一直有问题。需要注意每个函数都要有自己的@rdname和@export或者@method/@S3method。 - dardisco

对于仍然在多年后来到这里的任何人，截至Roxygen2 6.0.1版本，@S3method已被弃用并提示“警告：script.R:302：@S3method已被弃用，请使用@export代替”。 @method + @export可解决问题，但是仅使用@export仍会导致R CMD check出现警告。 - Scott Gigante

从 roxygen2-7.1.1 开始，不再建议使用 @S3method unknown tag，而是建议使用 @exportS3Method generic class。 - r2evans