23

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):


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

Community
  • 1
  • 1
Andrie
  • 176,377
  • 47
  • 447
  • 496
  • 1
    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 :-( – Ari B. Friedman Jul 01 '12 at 21:18
  • 2
    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? – Gavin Simpson Jul 01 '12 at 21:31
  • 1
    @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. – Andrie Jul 01 '12 at 21:42
  • 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. – Gavin Simpson Jul 01 '12 at 21:47
  • 1
    If `roxygen2` is not producing correct output by default, please file a bug report. You also shouldn't need `@aliases`, `@name`, or `@rdname` – hadley Jul 02 '12 at 02:30
  • @hadley I have filed an issue at https://github.com/klutometis/roxygen/issues/102 – Andrie Jul 02 '12 at 10:38

2 Answers2

15

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{}.

Gavin Simpson
  • 170,508
  • 25
  • 396
  • 453
  • +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! – Andrie Jul 01 '12 at 21:54
3

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.

tim
  • 3,559
  • 1
  • 33
  • 46