使用@inheritParams继承shiny::renderTable参数时rownames文档缺失求助

自定义的renderSemanticTable函数签名如下：

renderSemanticTable <- function(expr, 
                                format = c("striped", "selectable"),
                                type = c("auto", "definition", "structured"),
                                rownames = FALSE,
                                colnames = TRUE,
                                align = NULL,
                                color = NULL,
                                invert_color = FALSE,
                                stacking = c("auto", "unstackable", "tablet stackable"),
                                column_sizing = "auto",
                                fixed = FALSE,
                                size = c("auto", "small", "large"),
                                escape = TRUE) 

为复用参数文档，在roxygen2注释中添加：

#' @inheritParams shiny::renderTable

但生成的.Rd文件中没有rownames的文档条目，查看shiny::renderTable源码发现，rownames与colnames是被放在同一段文档中描述的。

原因分析 #

roxygen2的@inheritParams是按**@param注释块**来识别并继承文档的，而非逐个参数匹配。当原函数中多个参数（比如shiny::renderTable的rownames和colnames）共享同一段@param注释时，继承工具只会保留第一个参数（colnames）的文档条目，后续共享文档的参数（rownames）不会被自动拆分生成独立条目，因此最终.Rd文件中丢失了rownames的文档。

解决办法 #

可以通过以下方式解决：

• 手动补充rownames的参数文档：在roxygen注释中单独为rownames添加@param注释，直接复用shiny::renderTable中的描述即可，示例：

  #' @inheritParams shiny::renderTable
  #' @param rownames 是否显示行名，逻辑值，默认`FALSE`。若设为`NA`，则仅当行名为字符型时显示
  

• 使用参数筛选+手动补充：如果需要更精细的控制，可先排除共享文档的参数，再分别补充，但第一种方式更直接高效。

是否属于bug？ #

这不属于roxygen2的bug，是@inheritParams的预期设计行为：它无法自动识别并拆分原函数中多个参数共享的单段@param注释。如果希望该场景得到优化，可以向roxygen2仓库提交feature request，但无需提交bug报告。

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