氧气 : how to document method without cluttering the help index?

Question

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

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

更新:刚刚从 R CMD Check 中注意到以下内容:

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