使用 roxygen2 记录新的“+”S3 方法时出现问题

Question

我正在尝试在我的包中为类定义一个新的“+”S3 方法

class1

。我使用

roxygen2

生成函数手册页，在记录函数的使用情况时遇到问题，该问题要么是手册页中奇怪的“用法”部分，要么是检查包时出现警告。

这个“+”S3方法可以像标准加法一样接受一个或两个操作数：

#' Add objects of type "class1"
#' @rdname add.class1
#' 
#' @param x an object of class "class1"
#' @param y an object of class "class1"
#'
#' @return an object of class "class1"
#' @export
"+.class1" <- function(x, y = NULL) {
    if(!is.null(y)) {
        return(class1(x$value + y$value))
    } else {
        return(class1(+ x$value))
    }
}

如果我没有在

@usage

文档块中指定任何

roxygen2

部分，当我生成手册页（使用

devtools::document()

）并阅读函数文档（使用

?"+.class1"

）时，我会在手册页的“用法”部分（我认为这不是很清楚）：

## S3 method for class 'class1'
x + y = NULL

如果我在

@usage

方法的

roxygen2

文档块中指定

+.class1

部分，如下所示：

#' Add objects of type "class1"
#' @rdname add.class1
#' @usage
#' +x
#' x + y
#'
#' @param x an object of class "class1"
#' @param y an object of class "class1"
#'
#' @return an object of class "class1"
#' @export
"+.class1" <- function(x, y = NULL) {
    if(!is.null(y)) {
        return(class1(x$value + y$value))
    } else {
        return(class1(+ x$value))
    }
}

我在手册页中看到了一个漂亮的“用法”部分：

+x
x + y

但是我在检查包裹时收到警告：

Objects in \usage without \alias in documentation object '+.class1':
  ‘+’

我可以使用

roxygen2

在

@aliases +

文档块中添加别名，如下所示：

#' Add objects of type "class1"
#' @rdname add.class1
#' @aliases +
#' @usage
#' +x
#' x + y
#'
#' @param x an object of class "class1"
#' @param y an object of class "class1"
#'
#' @return an object of class "class1"
#' @export
"+.class1" <- function(x, y = NULL) {
    if(!is.null(y)) {
        return(class1(x$value + y$value))
    } else {
        return(class1(+ x$value))
    }
}

然后警告就消失了，但实际上我正在使用自己的“+”S3方法实现两个类，然后如果我有一个

@usage

标签（以获得漂亮的手册页“用法”部分）和

@aliases +

标签（为了避免我上面提到的警告）在两个类

roxygen

文档块（参见下文）中，我收到一个新警告：

Rd files with duplicated alias '+':
  ‘add.class1.Rd’ ‘add.class2.Rd’

class1

和

class2

“+”S3方法的定义：

#' Add objects of type "class1"
#' @rdname add.class1
#' @aliases +
#' @usage
#' +x
#' x + y
#'
#' @param x an object of class "class1"
#' @param y an object of class "class1"
#'
#' @return an object of class "class1"
#' @export
"+.class1" <- function(x, y = NULL) {
    if(!is.null(y)) {
        return(class1(x$value + y$value))
    } else {
        return(class1(+ x$value))
    }
}

#' Add objects of type "class2"
#' @rdname add.class2
#' @aliases +
#' @usage
#' +x
#' x + y
#'
#' @param x an object of class "class2"
#' @param y an object of class "class2"
#'
#' @return an object of class "class2"
#' @export
"+.class2" <- function(x, y = NULL) {
    if(!is.null(y)) {
        return(class2(x$value + y$value))
    } else {
        return(class2(+ x$value))
    }
}

Answer 1

帮助页面中使用的

+.Date

语法是

\special{date + x}

（参见https://github.com/wch/r-source/blob/d99a0b4cfe4435b212f0eb689ba0b853310c9695/src/library/base/man/Ops.Date.Rd#L19）

据我所知，

\special{}

宏几乎完全没有文档记录，因此您可能会收到某种使用它的警告。

bit64

包使用不同的语法：

\method{+}{integer64}(e1,e2)

显示为

## S3 method for class 'integer64'
e1 + e2

（参见https://github.com/truecluster/bit64/blob/e428535bc31982d85bc3f4faa1f2ae8481280781/man/xor.integer64.rd#L35）

这似乎是一个更好的选择。我没有找到一元运算符的示例。