How to add class-specific alias without generic alias using Roxygen2?

Question

A simple example is that I have created an extension to show, which is a S4 base method. I don't want to cause a disambiguation fork by re-documenting show in my package, and I also want to consolidate the documentation of my extension to show in the documentation for the new class, myPkgSpClass, by adding an alias for show,myPkgSpClass-method.

#' @export
#' @aliases show,myPkgSpClass-method
#' @rdname myPkgSpClass-class
setMethod("show", "myPkgSpClass", function(object){ show(NA) })

The problem I'm having, is that this results in an serious warning during documentation-build by roxygen2, Rd files with duplicated alias 'show': because there is more than one class extension to show in this package, and roxygen2 has automatically added the generic term in the list of aliases to all the relevant *-class.Rd files:

\alias{show}
\alias{show,myPkgSpClass-method}

But I think I don't want the generic alias in any of the instances, because it will force the need for disambiguation between show in my package, and the base show. This issue also applies to other S4 methods extended from other packages besides show.

If I tag all class-specific methods to the same .Rd file, then the warning goes away, but the ambiguity remains, because the show alias still gets added automatically for that doc entry. If I manually remove \alias{show} from the .Rd file, then the problem seems solved, no warnings during roxygen or R CMD check pkgname. So how do I get Roxygen2 to not-add the generic alias?

Other background:

This is a specific question building from a previous issue for exporting/documenting S4 extensions to base methods: Is it necessary to export base method extensions in an R package? Documentation implications?

It is more specific than, and not covered by, the following questions regarding documenting S4 methods / classes using Roxygen2:

How to properly document S4 methods using roxygen2

How to properly document S4 class slots using Roxygen2?

github.com/klutometis/roxygen/issues/75 Not sure if this applies only to S4. Haven't tested on S3 generics. — Paul McMurdie
This error still persists in version 2.2.2 on CRAN (comment added to the issue on github). It's fixed in the S4 branch, but that one seems inactive for the past two years. It's definitely not fixed on CRAN. — Joris Meys
I just spotted this on Twitter:Hadley Wickham ‏@hadleywickham 3h roxygen2 3.0.0 adds comprehensive S4 (and RC) support, better S3 support, and much much more: blog.rstudio.org/2013/12/09/roxygen2-3-0-0 … #rstats — Stephen Henderson
Yep, I haven't tested roxygen 3.0 yet, but it reports to handle S4 documentation automatically. For this particular issue I'm not sure yet what it expects, but I will post an answer when I figure it out (if no one beats me to it). — Paul McMurdie

Karl Forner Karl Forner · Accepted Answer · 2014-03-21T10:28:45

Seems to be fixed in roxygen2_3.1.0:

#' @export
#' @aliases show,myPkgSpClass-method
#' @rdname myPkgSpClass-class
setMethod("show", "myPkgSpClass", function(object){ show(NA) })

produces the myPkgSpClass-class.Rd:

\docType{methods}
\name{show,myPkgSpClass-method}
\alias{show,myPkgSpClass-method}
\usage{
\S4method{show}{myPkgSpClass}(object)
}
\arguments{
  \item{object}{Any R object}
}

As Hadley stated, you do not need anymore to explicitly set the alias or the rd name, e.g.:

#' my title
#' @export
setMethod("show", "myPkgSpClass", function(object){ show(NA) })

will generate show-myPkgSpClass-method.Rd:

\docType{methods}
\name{show,myPkgSpClass-method}
\alias{show,myPkgSpClass-method}
\title{my title}
\usage{
\S4method{show}{myPkgSpClass}(object)
}
\arguments{
  \item{object}{Any R object}
}
\description{
my title
}

Note that in that case you have to set the description. It will not generate a doc page if the documentation entry is empty.

How to add class-specific alias without generic alias using Roxygen2?

1 Answers