我正在尝试将方法记录在与泛型相同的文件中。我希望usage部分包含该方法，但不希望为该方法生成别名。这是因为我有很多泛型的方法，并且我希望保持索引相对干净。
我尝试了@rdname和@describeIn，但它们似乎都自动生成了一个alias标记，然后显示在索引中。我可以通过手动编辑Rd文件并删除alias{}条目来获得所需的结果，但这是不可持续的。
更新：刚刚从R CMD检查中注意到以下内容：
具有\用法项的函数需要具有适当的\别名条目，并记录它们的所有论点。
所以也许我要找的甚至都不合法。
您可以使用多行@useage，如下所示：
#' a generic called foo
#'
#' @param x the only named parameter
#'
#' @usage
#' # you can call `foo()` this way
#' foo(x, ..., [n, ybar,])
#' # or this way
#' foo(x, ..., na.rm = FALSE, details = FALSE)
#' # or even this way
#' foo(x, ..., [n, ybar,] na.rm = FALSE, details = FALSE)
foo <- function(x,...)
return('hello world')
生成以下CCD_ 7文件：
% Generated by roxygen2 (4.1.0): do not edit by hand
% Please edit documentation in R/peb-utils.r
name{foo}
alias{foo}
title{a generic called foo}
usage{
# you can call `foo()` this way
foo(x, ..., [n, ybar,])
# or this way
foo(x, ..., na.rm = FALSE, details = FALSE)
# or even this way
foo(x, ..., [n, ybar,] na.rm = FALSE, details = FALSE)
}
arguments{
item{x}{the only named parameter}
}
description{
a generic called foo
}
不幸的是，这确实在R CMD check:中引发了一些警告
* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'foo':
foo
Code: function(x, ...)
Docs: function(x, ..., na.rm = FALSE, details = FALSE)
Argument names in docs not in code:
na.rm details
* checking Rd usage sections ... WARNING
Undocumented arguments in documentation object 'foo'
'...' 'na.rm' 'details'
Bad usage lines found in documentation object 'foo':
foo(x, ..., [n, ybar,])
foo(x, ..., [n, ybar,] na.rm = FALSE, details = FALSE)
Functions with usage entries need to have the appropriate alias
entries, and all their arguments documented.
The usage entries must correspond to syntactically valid R code.
See the chapter 'Writing R documentation files' in the 'Writing R
以下是一种使用roxygen 5.0.0+导出泛型函数方法的方法，而无需同时创建别名，这样这些方法就不会在索引中列出，但仍会在泛型函数的帮助页中正确记录。与@Jthorpe提出的方法相比，其优点有两个：
-
您不必手动拼写方法的调用签名（毕竟，您已经通过首先定义方法做到了这一点）。
-
除了
@-标签提供的功能外，所采用的技术通常可用于使用roxygen操作Rd文件结构。
首先，以通常的方式导出泛型/方法。请注意，没有@rdname，因此不会创建别名。
#' @export
my_generic <- function(x, ...) UseMethod("my_generic")
#' @export
my_generic.default <- function(x, a = NULL, ...) "Default method"
#' @export
my_generic.numeric <- function(x, a = 0, ...) "Numeric method"
接下来，为my_generic提供一个roxygen块。该块值得注意的特征是：1）将（由@name）为通用函数创建一个别名，但不为其任何方法创建别名；2） @evalRd标记（自roxygen 5.0.0起可用）评估其代码以创建Rd文件的usage部分，程序化。
#' My generic function
#'
#' @evalRd rd_s3_usage("my_generic", "default", "numeric")
#' @param x Some object.
#' @param a Some object.
#' @param ... Stuff.
#' @name my_generic
NULL
函数rd_s3_usage()创建所需的usage块作为（转义）字符串，其格式适合记录S3方法。
cat(rd_s3_usage("my_generic", "default", "numeric"))
#> usage{
#> my_generic(x, dots)
#>
#> method{my_generic}{default}(x, a = NULL, dots)
#>
#> method{my_generic}{numeric}(x, a = 0, dots)
#> }
在创建rd_s3_usage()时，我编写了比手头任务所需的更通用的辅助函数，因为这些函数可以在其他需要以编程方式生成Rd块的情况下重用（或调整）。
rd_dots <- function(x) gsub("\.\.\.", "\\dots", x)
# Figure out calling signature of a function (given by name)
call_sig <- function(nm, cmd = nm, ...) {
f <- get(nm, mode = "function", ...)
sig <- deparse(call("function", formals(f), quote(expr = )))
sig <- paste(trimws(sig, which = "left"), collapse = "")
sig <- sub("^function", cmd, trimws(sig, which = "both"))
rd_dots(sig)
}
# Make a vector of usage{} entries for an S3 generic
s3_methods <- function(generic, ...) {
classes <- list(...)
rd_tmpl <- sprintf("\\method{%s}{%%s}", generic)
cs_methods <- vapply(classes, function(cls) {
method <- paste(generic, cls, sep = ".")
rd_cmd <- sprintf(rd_tmpl, cls)
call_sig(method, rd_cmd)
}, character(1))
c(call_sig(generic), cs_methods)
}
# Rd command markup
rd_markup <- function(cmd, join, sep) {
force(join); force(sep)
rd_cmd_opening <- paste0("\", cmd, "{")
function(x)
paste(rd_cmd_opening, paste(x, collapse = join), "}", sep = sep)
}
rd_s3_usage <- function(...)
rd_markup("usage", join = "nn", sep = "n")(s3_methods(...))
遗憾的是，运行R CMD check仍然会产生可怕的Objects in usage without alias in documentation object 'my_generic'错误。似乎必须设置方法别名才能避免这种情况。