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

Question

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

Functions/methods with usage in documentation object 'print.surveyor' but not in code: print

我使用了 Hadley 撰写的以下两页作为灵感: Namespaces和 Documenting functions ，两者都表明正确的语法是 @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)
}

以及氧化输出，即 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 等时执行适当的操作。

在某些异常(exception)情况下，您可能需要帮助roxygen。安example Hadley Wickham 在他的 R Packages 书中使用的是 all.equal.data.frame。该函数名称对于什么是类以及什么是通用函数(all、all.equal 或 all.equal.data)？

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

@method all.equal data.frame

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

<小时/>

原版

该函数应使用 @method 标记进行记录:

#' @method print surveyor

在初次阅读时，@hadley 的文档对我来说有点困惑，因为我不熟悉 roxygen，但在多次阅读该部分后，我想我明白您需要 @方法。

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

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

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

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