Assignment function documentation fails R CMD CHECK

Question

I'm having trouble with checking assignment functions with Roxygen.

Here's a fairly minimal example:

#' Get sp feature IDs
#' @aliases IDs IDs.default IDs.SpatialPolygonsDataFrame IDs<- IDs<-.SpatialPolygonsDataFrame
#' @param x The object to get the IDs from or assign to
#' @param value The character vector to assign to the IDs
#' @param \dots Pass-alongs
#' @author Ari B. Friedman
#' @rdname IDs
IDs <- function(x,...) {
  UseMethod("IDs",x)
}
#' @method IDs default
#' @S3method IDs default
#' @rdname IDs
IDs.default <- function(x,...) {
  stop("Currently only SpatialPolygonsDataFrames are supported.")
}
#' @method IDs SpatialPolygonsDataFrame
#' @S3method IDs SpatialPolygonsDataFrame
#' @rdname IDs
IDs.SpatialPolygonsDataFrame <- function(x,...) {
  vapply(slot(x, "polygons"), function(x) slot(x, "ID"), "")
}

#' Assign sp feature IDs
#' @rdname IDs
"IDs<-" <- function( x, value ) {
  UseMethod("IDs<-",x)
}
#' @method IDs<- SpatialPolygonsDataFrame
#' @S3method IDs<- SpatialPolygonsDataFrame
#' @rdname IDs
"IDs<-.SpatialPolygonsDataFrame" <- function( x, value) {
  spChFIDs(x,value)
}

And when I run check:

* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'IDs':
IDs<-
  Code: function(x, value)
  Docs: function(x, value, value)
IDs<-.SpatialPolygonsDataFrame
  Code: function(x, value)
  Docs: function(x, value, value)

I don't understand where the second value is coming from. I've tried eliminating the @param value on the theory that maybe Roxygen automatically creates an entry for assignment functions, but that doesn't eliminate the (x,value,value) definition and produces a new warning complaining that I haven't defined value.

Here's the relevant portion of the .Rd generated:

\usage{
  IDs(x, ...)

  \method{IDs}{default} (x, ...)

  \method{IDs}{SpatialPolygonsDataFrame} (x, ...)

  IDs(x, value) <- value

  \method{IDs}{SpatialPolygonsDataFrame} (x, value) <-
    value
}

I don't see the (x, value, value) signature that check claims is there.

This is an S3 function but it's operating on a S4 object. That should still make it S3, I think. But if not it might be that my use of @S3method is the problem.

Help?

It's probably because S4 support in roxygen2 sucks :( You can try the experimental [roxygen3](http://github.com/hadley/roxygen3/) which will be merged back into roxygen2 at some point in the future. — hadley, Nov 10 '12 at 13:22
This seems to be related: http://stackoverflow.com/questions/8873514/documenting-setter-functions-with-roxygen — Dason, Nov 12 '12 at 15:27

score 5 · Accepted Answer · answered Nov 12 '12 at 18:42

This is a rather hackish way to go about it but it appears that the way roxygen handles this is still broken for the time being (LINK). But you can manually add the usage section into your roxygen comments directly.

#' Assign sp feature IDs
#' @rdname IDs
#' @usage IDs(x) <- value
"IDs<-" <- function( x, value ) {
    UseMethod("IDs<-",x)
}

#' @method IDs<- SpatialPolygonsDataFrame
#' @S3method IDs<- SpatialPolygonsDataFrame
#' @rdname IDs
#' @usage IDs(x) <- value
"IDs<-.SpatialPolygonsDataFrame" <- function( x, value) {
    spChFIDs(x,value)
}

Assignment function documentation fails R CMD CHECK

1 Answers1