R CMD check warning: Functions/methods with usage in documentation object ... but not in code

Question

I am writing a package but one persistent R CMD check warning prevents me from finishing the package and posting it to CRAN. I use roxygen2 for inline documentation, although that possibly isn't the root cause of the error.

If you know what to do to remove this warning, I can quite possibly figure out a way of doing it using roxygen2.

How can I remove the warning Functions/methods with usage in documentation object ... but not in code from my package checks?

---

The R CMD check warning:

* checking for code/documentation mismatches ... WARNING
Functions/methods with usage in documentation object 'names<-' but not in code:
  names<-

The function and roxygen documentation:

#' Updates names and variable.labels attribute of surveydata.
#' 
#' @name names<-
#' @rdname names
#' @aliases names<- names<-.surveydata
#' @param x surveydata object
#' @param value New names
#' @method names<- surveydata
#' @usage names(x) <- value
"names<-.surveydata" <- function(x, value){
    invisible(NULL)
}

The resulting .rd documentation file:

\name{names<-}
\alias{names<-}
\alias{names<-.surveydata}
\title{Updates names and variable.labels attribute of surveydata.}
\usage{
  names(x) <- value
}
\arguments{
  \item{x}{surveydata object}

  \item{value}{New names}
}
\description{
  Updates names and variable.labels attribute of
  surveydata.
}

---

I have cross-checked my documentation with the documentation for names<- in base R, and it seems identical:

\title{  The Names of an Object}
\name{names}
\alias{names}
\alias{names.default}
\alias{names<-}
\alias{names<-.default}
\keyword{attribute}
\description{Functions to get or set the names of an object.}

---

Related question (but I have already implemented the suggestion and still no luck):

• How to properly document a S3 method of a generic from a different package, using Roxygen?

---

Where am I going wrong? How can I remove this warning from the package checks?

Dierolf

I'm pretty sure this is not a roxygen2 problem but a problem that crops up when you have a method in your package for which the generic is in another package. I'm pretty sure I've run into similar problems in the past but unfortunately I can't remember the solution right now :-( – Dermato

I don't think you want the @usage section. In my Rd files of similar nature, you want usage to include \method{names}{surveydata}(x) <- value which should be produce by the @method section. If it isn't after you delete the @usage line, then add an explicit @usage line containing the above? – Adjoint

@GavinSimpson That approach seems to work, thank you. However, by default, roxygen doesn't generate that usage, hence the override statement. I shall report this as a bug / new feature request. – Dierolf

If you are documenting both the names.surveydata() and "names<-.surveydata()" in the same file, I'd add both in the @usage, if you are documenting them separately then it doesn't matter. – Adjoint

If roxygen2 is not producing correct output by default, please file a bug report. You also shouldn't need @aliases, @name, or @rdname – Tera

@Tera I have filed an issue at github.com/klutometis/roxygen/issues/102 – Dierolf

Answer 1

The \usage section in the Rd file needs to include the following:

\method{names}{surveydata}(x) <- value

If this is not automatically inserted by the @method line (I presume that will only add \method{names}{surveydata}(x)?) then you need an explicit @usage section that includes the above. Something like

#' @usage \\method{names}{surveydata}(x) <- value

I would also change the @name and @alias sections to refer to the method explicitly not the generic as that will clash with the Rd file in R::base.

Essentially, the warning is coming from the fact that your package doesn't contains a function "names<-" yet you are using this in \usage{}.

Adjoint

+1 This seems to work - I no longer get any R CMD check warnings. Thank you also for the additional tips about @name and @alias. I'll study these carefully - they most likely have been mangled in this way in my attempts to satisfy the package check mechanism! – Dierolf

Answer 2

In case it helps anyone, this error can also arise from an abandoned Rd file for which a function or data object no longer exists.

Blimey