如何使用 Roxygen 正确记录来自不同包的泛型的 S3 方法？

Question

我正在编写一个包，它定义了一个新类、surveyor 和一个为此的 print 方法，即 print.surveyor。我的代码工作正常，我使用 roxygen 进行内联文档。但是 R CMD check 发出警告：

使用的函数/方法 文档对象“print.surveyor” 但不在代码中： print

我使用了 Hadley 编写的以下两页作为灵感： 命名空间 和 记录函数，两者都指出正确的语法是 @method function-name class

所以我的问题是：什么是记录的正确方法使用 Roxygen 为我的新类添加 print 方法？更具体地说，我如何摆脱警告？

---

这是我的代码：（注释文档表明尝试修复此问题，但没有一个起作用。）

#' Prints surveyor object.
#' 
#' Prints surveyor object
#' 
## #' @usage print(x, ...)
## #' @aliases print print.surveyor
#' @param x surveyor object
#' @param ... ignored
#' @S3method print surveyor
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

以及 roxygenized 输出，即 print.surveyor .Rd：

\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object

#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}

Answer 1

更新

截至 roxygen2 > 3.0.0 该软件包在为您解决所有这些问题方面变得更加智能。您现在只需要 @export 标签，roxygen 就会计算出什么您正在记录的事情，并在转换期间编写 NAMESPACE 等时执行适当的操作。

在某些例外情况下，您可能需要帮助roxygen。 Hadley Wickham 在他的 R 包中使用的示例 书是all.equal.data.frame。该函数名称对于什么是类以及什么是通用函数（all、all.equal 或 all.equal.data< /代码>）？

在这种情况下，您可以通过显式告知 roxygen 泛型和类/方法来帮助它，例如，

@method all.equal data.frame

如果您需要显式使用 @method，下面的原始答案解释了有关旧行为的更多信息。

---

原始

函数应使用 @method 标签进行记录：

#' @method print surveyor

在初次阅读时，@hadley 的文档对我来说有点混乱，因为我不熟悉 roxygen，但经过几次阅读后阅读该部分的内容后，我想我理解您需要 @method 的原因。

您正在为 print 方法编写完整文档。 @S3method 与 NAMESPACE 相关，并安排要导出的方法。 @S3method 并不用于记录方法。

您的 Rd 文件的 usage 部分应包含以下内容：

\method{print}{surveyor}(x, ...)

如果工作正常，因为这是在 Rd 文件中记录 S3 方法的正确方法。

Answer 2

就roxygen2而言， 3.0.0.，您只需要 @export 因为 roxygen 可以确定 print.surveyor 是一个 S3 方法。这意味着您现在只需要

#' Prints surveyor object.
#' 
#' @param x surveyor object
#' @param ... ignored
#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

然而，在这种情况下，由于文档不是很有用，最好只执行以下操作：

#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

Answer 3

@export 仅在加载泛型时才有效。如果泛型位于另一个包中，则需要导入泛型。 块来解决此问题

#' @importFrom tibble data_frame
#' @export
tibble::data_frame

在当前的 roxygen 中，可以使用来自 dplyr/ 的 R/reexport-tibble.r。在此示例中，从 tibble 包导入 data_frame 方法，并导出 tibble::data_frame。然后，此类重新导出的对象将记录在 reexports.Rd 文件中，不用说，该文件满足 R CMD 检查。