R语言中用roxygen2为自定义FOO类length方法补全文档参数

首先直接给你答案：

• @aliases 后的XXX应该填 length,FOO-method
• @rdname 后的YYY推荐填 length（或者你也可以用自定义名称比如length-FOO，后面会解释区别）

为什么要这么填？ #

在R的S4方法文档规范里：

1. @aliases的作用：用来指定方法的唯一标识符，格式固定为泛型函数名,类名-method。这里你的泛型是length，自定义类是FOO，所以完整的方法标识符就是length,FOO-method，这样roxygen2这类文档生成工具才能正确识别这是属于FOO类的length方法。

2. @rdname的作用：用来把多个相关的文档条目归为一组。

   • 如果你填length，这个方法的文档会被合并到基础R中length泛型的文档里，用户执行?length时就能看到针对FOO对象的length方法说明，这是更符合用户使用习惯的做法。
   • 如果你想为这个方法单独生成一个独立的文档页面，可以填自定义名称比如length-FOO，之后用户需要执行?length-FOO才能看到这个方法的说明。

修正后的完整代码示例 #

#' Returns the length of the FOO object
#'
#' @name length
#' @param x a FOO object
#' @aliases length,FOO-method
#' @rdname length
#' @docType methods
setMethod("length", "FOO", function(x) { nrow(x$BLAH) })

测试一下，当你定义好这个方法后，创建FOO对象调用length()依然会返回正确的结果，同时文档生成工具也能正确识别并生成对应的帮助文档。

内容的提问来源于stack exchange，提问作者January