Question

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

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

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

使用\ usage条目的函数需要具有相应的\别名条目及其所有参数都记录在案。

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

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文件结构，超出@ - 标签提供的功能。

首先，以通常的方式导出您的通用/方法。请注意，没有@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()以正确的格式记录S3方法，以（转义的）字符串创建所需的\usage块。

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：如何在没有混乱帮助索引的情况下记录方法？

2 个答案: