Roxygen2：用可选参数记录一个函数答案

【问题标题】：Roxygen2: document a function with an optional parameterRoxygen2：用可选参数记录一个函数
【发布时间】：2016-10-19 21:11:35
【问题描述】：

roxygen 用可选参数记录函数的正确方法是什么

#' @name dbh2vol
#' @usage dbh2vol(dbh,ipft)
#' @description This is an allometric function to return the tree volume
#' @param dbh diameter at breast height
#' @param ipft PFT
#' @return vol volume
#' @export

dbh2vol <- function(dbh,ipft,...,hgt, chambers = FALSE){

  if (missing(hgt)) hgt = other_function (dbh, ipft)
  vol  = hgt * dbh ^ pft$vol[ipft]
  if (chambers) vol = vol * 2

  return(vol)
}

尤其应该如何评论可选参数chambers和hgt？

【问题讨论】：

我不确定我是否理解...为他们添加 @param 条目...？
并省略@usage
那么重点是hgt和chambers这两个参数在本质上与其他参数不同，因为它们是可选的。其中一个设置为TRUE，而另一个调用外部函数。告知文档读者这方面的正确方法是什么？
我同意@R Kiselev 的回答。可能 R 中大多数内置函数中的大多数参数都是可选的，因为用户不需要触摸它们，除非他们有理由这样做。在函数定义中，这些的默认值可以设置为FALSE或NULL。例如。 Fun = function(data, weights=NULL, adjust=FALSE, verbose=FALSE, plot.it=TRUE){。在@param 和@details 部分中，您可以添加尽可能多的描述，以便用户正确理解和使用该功能。

标签： r roxygen2

【解决方案1】：

我只需为每个参数添加一个@param 字段，并明确写入参数是否是可选的，如下所示：

#' @name dbh2vol
#' @usage dbh2vol(dbh,ipft)
#' @description This is an allometric function to return the tree volume
#' @param dbh diameter at breast height
#' @param ipft PFT
#'
#' @param chambers  optional parameter that is blah-blah... FALSE by default
#' @param hgt  function to do this and that (optional).
#'             If not provided, \code{other_function(dbh, ipft)} is used.
#'
#' @return vol volume
#' @export

dbh2vol <- function(dbh,ipft,...,hgt, chambers = FALSE){

  if (missing(hgt)) hgt = other_function (dbh, ipft)
  vol  = hgt * dbh ^ pft$vol[ipft]
  if (chambers) vol = vol * 2

  return(vol)
}

如果您的用户阅读文档，那么他/她会知道这些参数是可选的。如果不是，他/她将通过省略这些论点通过实验来解决。

希望这会有所帮助。

P.S. 良好的 R 编码习惯要求您记录每个函数参数。如果不这样做，Roxygen2 会在检查包时发出警告。

【讨论】：