无默认值且参数分离的S3方法添加Roxygen2注释的最佳实践

通用函数的注释写法 #

通用函数作为调度入口，要明确说明泛型的作用、通用参数范围，以及不同方法专属参数的适用场景，确保用户能清晰区分哪些参数对应哪类输入对象。

示例代码：

#' 处理不同类型对象的泛型函数
#'
#' 根据输入对象的类型（`a`类或`b`类）调用对应方法处理，支持通用参数及类型专属参数。
#'
#' @param x 输入对象，必须是`a`类或`b`类实例
#' @param common_par 所有类型对象都需要的通用参数
#' @param other_par1 仅当`x`为`a`类对象时需传入的专属参数（无默认值）
#' @param other_par2 仅当`x`为`b`类对象时需传入的专属参数（无默认值）
#' @export
#' @family 对象处理函数
f <- function(x, common_par, other_par1, other_par2) {
    UseMethod("f")
}

方法的注释写法 #

每个S3方法的注释要关联到对应泛型，仅补充该方法特有的参数说明，无需重复泛型的通用描述。用@describeIn将方法文档合并到泛型的条目下，方便用户统一查看。

处理a类对象的方法 #

#' @describeIn f 处理`a`类对象的专属方法
#' @param other_par1 针对`a`类对象的专属参数，用于[替换为实际业务场景，如数据校验规则]
#' @export
f.a <- function(x, common_par, other_par1) {
    print(c(x, common_par, other_par1)) # 示例逻辑
}

处理b类对象的方法 #

#' @describeIn f 处理`b`类对象的专属方法
#' @param other_par2 针对`b`类对象的专属参数，用于[替换为实际业务场景，如结果输出格式]
#' @export
f.b <- function(x, common_par, other_par2) {
    print(c(x, common_par, other_par2)) # 示例逻辑
}

关键最佳实践要点 #

• 通用函数参数全覆盖：泛型函数要包含所有方法可能用到的参数，确保调度时参数传递无遗漏，注释需明确标注每个参数的适用对象类型。
• 方法注释关联泛型：用@describeIn替代单独编写@title，让方法文档与泛型合并，用户查看文档时可在同一页面获取所有相关方法的信息。
• 参数说明精准精简：每个方法仅聚焦自身特有的参数，通用参数的说明直接复用泛型的内容，避免冗余。
• 导出灵活控制：如果允许用户直接调用方法（而非仅通过泛型调度），则添加@export；若仅通过泛型调用，可省略方法的@export，减少命名空间污染。

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