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

问题

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?

回答1:

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.

来源：https://stackoverflow.com/questions/8947483/how-to-add-class-specific-alias-without-generic-alias-using-roxygen2

标签

documentation

roxygen

roxygen2