Roxygen：如何在不使帮助索引混乱的情况下记录方法？

Question

我正在尝试在与泛型相同的文件中记录方法。我希望 usage 部分包含该方法，但我不希望为该方法生成别名。这是因为我有很多通用方法，我想保持索引相对干净。

我已经尝试了 @rdname 和 @describeIn，但它们似乎都自动生成了一个 \alias 标签，然后该标签显示在索引中。我可以通过手动编辑 Rd 文件并删除 \alias{} 条目来获得所需的结果，但这并不是真正可持续的。

更新：刚刚从 R CMD 检查中注意到以下内容：

Functions with \usage entries need to have the appropriate \alias entries, and all their arguments documented.

所以也许我正在寻找的东西甚至不合法。

Answer 1

您可以像这样使用多行@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')

生成以下 foo.Rd 文件：

% 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

Answer 2

这是一种使用 roxygen 5.0.0+ 导出通用函数方法而不同时创建别名的方法，因此这些方法不会在索引中列出，但仍会在帮助页面中正确记录通用功能。与@Jthorpe 提出的方法相比，优点有两个：

您不必手动拼出方法的调用签名（毕竟，您已经通过首先定义方法完成了）。
所采用的技术通常可用于使用 roxygen 操作 Rd 文件结构，超出了 @-tags 提供的功能。

首先，以通常的方式导出您的 generic/methods。请注意，没有 @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 的氧气块。这个块值得注意的特点是：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 = "\n\n", sep = "\n")(s3_methods(...))

唉，运行 R CMD check 仍然会产生可怕的 Objects in \usage without \alias in documentation object 'my_generic' 错误。看来必须设置方法别名才能避免。

Roxygen：如何在不使帮助索引混乱的情况下记录方法？

Roxygen: how to document method without cluttering the help index?

r

roxygen2