Roxygen如何处理中缀二元运算符（例如%in%）？

Question

作为一个简单的具体例子：

#' 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) )
}

然而，当我尝试构建一个包时，函数似乎被忽略了，没有生成文档。

在http://cran.r-project.org/doc/manuals/r-release/R-exts.html#Documenting-functions上有关于二进制中缀函数的一行简短介绍，但我很难解析它，并且不知道对Roxygen文档意味着什么。

- Kevin Ushey

Answer 1

在使用部分，您需要转义%。此外，我认为您可能需要指定一个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) )
}

---

这是我个人包中的一个函数。我不认为我曾经真正使用过该函数，但是roxygenize确实创建了一个帮助文件并且该包通过了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)

- GSee

---

@hadley，如果没有它，我会得到一个NOTE“prepare_Rd：PctIn.Rd：4-6：删除空部分\usage”。除了这个NOTE之外，它似乎是有效的。 - GSee

哦，嗯，我猜那是一个转义问题。我需要完成roxygen3，然后将其合并回roxygen2中。 - hadley

描述中的葡萄也需要转义。 - Jack Wasey

Answer 2

我在使用roxygen（而非roxygen2）和中缀运算符时遇到了困难。以下是适用于我的设置（R 2.15.1，roxygen 0.1-3）的解决方案。

第一种解决方案：编辑每个中缀运算符的Rd文件（应该是grapes ... grapes.Rd），并在\alias、\usage和\name部分中用反斜杠转义每个%。

第二种解决方案：在中缀运算符的文档中指定@name和@usage标签，并转义%。以下是一个示例：

##' 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 = "")

- Dotoma