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

【问题标题】：How to properly document a S3 method of a generic from a different package, using Roxygen?如何使用 Roxygen 正确记录来自不同包的泛型的 S3 方法？
【发布时间】：2011-06-29 07:36:10
【问题描述】：

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

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

我使用了 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)
}

以及 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}}

【问题讨论】：

标签： r roxygen

【解决方案1】：

更新

从 roxygen2 > 3.0.0 开始，该软件包在为您解决所有这些方面变得更加智能。您现在只需要 @export 标记和 roxygen在转换过程中编写NAMESPACE 等时，将确定您正在记录什么样的事情并做适当的事情。

在某些情况下您可能需要帮助 roxygen。 Hadley Wickham 在他的R Packages 书中使用的example 是all.equal.data.frame。该函数名称对于什么是类以及什么是泛型函数（all、all.equal 或 all.equal.data）存在歧义？

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

@method all.equal data.frame

如果您需要明确使用@method，下面的原始答案会详细说明旧行为。

原创

函数应该用@method标签记录：

#' @method print surveyor

在最初阅读时，@hadley 的文档对我来说有点困惑，因为我不熟悉 roxygen，但是在阅读了该部分之后，我想我明白了您需要 @987654332 的原因@。

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

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

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

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

【讨论】：

谢谢，也一直在为此苦苦挣扎，但是如何将它与特定于类的 [-function，例如[.myClass?此解决方案通过R CMD check 没有警告，但生成的 Rd 标记是一团糟。 @method [ myClass 变为 \method{[}{myClass} (x, i, j, ...)。
@Backlin 这有什么问题？这看起来像是 Rd 中标记和 S3 方法的正确方法。它将在“使用”部分正确呈现，但在使用代码上方带有## S3 method blah blah。
哦不，我的错！我正在查看旧版本 R 中的文档，但它在新版本中正确呈现。希望我没有浪费你太多时间。
@Backlin - 不用担心。很高兴问答对您有用。
@cboettig 是的，@method 是文档的标签（.Rd 文件），@S3method 是命名空间机制的标签。如果您有自己的 NAMESPACE 文件，那么这两天都需要。如果你真的想让方法在包的命名空间之外可见，你只需要@export。

【解决方案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)
}

【讨论】：

整洁。谢谢你。我马上试试！
嗯。我想注册一个 S3 方法而不导出它。不幸的是，这会产生弃用警告。有没有办法解决这个问题？
@KonradRudolph 注册 S3 方法而不导出它是什么意思？
@hadley 我想避免使用@export，因为R CMD check 抱怨未记录的参数（我没有记录该方法，因为它应该是不可见的）。但是，我现在无法重现：没有生成 .Rd 文件，并且没有为缺少参数显示 R CMD check 警告。我可能事先在文档注释中有一些空行，导致为此方法生成的文档不完整。

【解决方案3】：

@export 仅在加载泛型时才有效。如果泛型在另一个包中，则需要导入泛型。使用当前的 roxygen，可以使用类似的块解决此问题

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

取自 dplyr/R/reexport-tibble.r 。在这个例子中，data_frame 方法是从 tibble 包中导入的，并且 tibble::data_frame 是导出的。此类重新导出的对象随后会记录在 reexports.Rd 文件中 - 不用说 - 满足 R CMD 检查。

【讨论】：