How does Roxygen to handle infix binary operators (eg. %in%)?

Question

As a simple, concrete example:

#' Inverse Value Matching
#' 
#' Complement of \code{%in%}. Returns the elements of \code{x} that are
#' not in \code{y}.
#' @usage x %nin% y
#' @param x a vector
#' @param y a vector
#' @export
"%nin%" <- function(x, y) {
  return( !(x %in% y) )
}

However, when I attempt to build a package the function seems to be ignored and no documentation is generated.

There seems to be a one-line blurb about binary infix functions at http://cran.r-project.org/doc/manuals/r-release/R-exts.html#Documenting-functions, but I am having a hard time parsing it, and what it would imply for Roxygen documentation.

Answer 1

You need to escape the %s in the usage section. Also, I think you may need to specify an rdname

#' Inverse Value Matching
#' 
#' Complement of \code{%in%}. Returns the elements of \code{x} that are
#' not in \code{y}.
#' @usage x \%nin\% y
#' @param x a vector
#' @param y a vector
#' @export
#' @rdname nin
"%nin%" <- function(x, y) {
  return( !(x %in% y) )
}

---

Here is a function I have in a personal package. I don't think I've ever actually used the function, but roxygenize does create a help file and the package passes R CMD check.

#' percent in
#' 
#' calculate the percentage of elements of \code{table} that are in \code{x}
#' 
#' @param x vector or NULL: the values to be matched
#' @param table vector or NULL: the values to be matched against
#' @return percentage of elements of \code{x} that are in \code{table}
#' @author gsee
#' @usage x \%pctin\% table
#' @examples
#' letters[1:10] %pctin% letters[1:3] # 30% of the second arg ar in the first
#' @export
#' @rdname PctIn
"%pctin%" <- function(x, table) length(x[x %in% table])/length(x)

Answer 2

I've had a hard time with roxygen (speaking of roxygen not roxygen2) and infix operators. Here's what worked with my setup (R 2.15.1, roxygen 0.1-3).

First solution: edit the Rd file of every infix operator (should be grapes ... grapes.Rd) and escape with a baskslash every % in the \alias, \usage and \nameparts.

Second solution: specify the tags @name and @usage in the documentation of the infix operator and escape the %. Here's an example:

##' Concatenates two strings
##'
##' @name \%+\%
##' @usage \%+\%(x, y)
##' @title Concatenation operator.
##' @param a String.
##' @param b String.
##' @return Same as paste0(a, b).
"%+%" <- function(a, b) paste(a, b, sep = "")