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

Question

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

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

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

带有 \usage 条目的函数需要有适当的 \alias 条目，并记录它们的所有参数。

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

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