Roxygen2 - 如何正确记录 S3 方法

Question

我已阅读 Roxygen2 PDF 和此 site ，并且我不知道 @method @S3method @export 之间的区别以及如何使用它们来正确记录 S3 方法。我编写了以下示例以供讨论:

1. 我该如何正确记录这些内容？
   
   
2. 如何模拟 ?print 和其他通用函数的文档，以显示所有特定于类的实现的用例(即 ?print 显示“因子”、“表”、“函数”用法的方式)
   
   
3. 来自 wiki 页面:“所有导出的方法都需要 @S3method 标记。它的格式与 @method 相同。这会导出方法，而不是函数 - 即 generic(myobject) 可以工作，但 generic.mymethod(myobject )不会。”
   我无法解释这一点。这似乎是说，如果标签指定不正确，函数/方法调用将无法正常工作？具体会破坏什么？

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

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
}