Roxygen2 - 如何正确记录S3方法

Question

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

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

2.如何模拟？print和其他通用函数的文档，这些函数显示所有特定于类的实现的用例（即方式？print显示'factor'，'table'，'function'的用法）

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

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

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

Answer 1

从roxygen2＆gt; 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字段中生成\ methods条目。

@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。”