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

Question

I'm trying to document methods in the same file as the generic. I want the usage section to contain the method, but I do not want an alias generated for the method. This is because I have many methods for the generic and I'd like to keep the index relatively clean.

I've tried both @rdname and @describeIn but both seem to automatically generate an \alias tag which then shows up in the index. I can get the desired result by manually editing the Rd file and removing the \alias{} entry, but that isn't really sustainable.

UPDATE: Just noticed the following from R CMD Check:

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

So maybe what I'm looking for is not even legal.

Answer 1

You can use a multi-line @useage like so:

#' 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')

which produces the following foo.Rd file:

% 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
}

Unfortunately, this does raise some warnings in the 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