Roxygen2: 使用可选参数记录函数

Question

如何正确使用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，应该如何进行评论呢？

- Manfredo

---

我不确定我理解了...为它们添加@param条目吗...？ - joran

and leave out the @usage - rawr

好的，问题是hgt和chambers这两个参数与其他参数本质上不同，因为它们是可选的。其中一个设置为TRUE，而另一个调用外部函数。正确的方式是如何告知文档读者关于这一点？ - Manfredo

我同意@R Kiselev的答案。在R中，大多数内置函数的大多数参数都是可选的，也就是说，用户不需要触及它们，除非他们有理由这样做。在函数定义中，这些参数的默认值可以设置为“FALSE”或“NULL”。例如：Fun = function(data, weights=NULL, adjust=FALSE, verbose=FALSE, plot.it=TRUE){}。在“@param”和“@details”部分，您可以添加尽可能多的描述，以便用户正确理解和使用该函数。 - Sal Mangiafico

Answer 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)
}

如果你的用户阅读文档，他/她就会知道这些参数是可选的。如果没有阅读文档，则可以通过省略这些参数进行实验性试探来解决问题。

希望这能有所帮助。

附言：良好的 R 代码编写规范要求你记录每一个函数参数。如果不这样做，Roxygen2 在包检查期间会发出警告。

- R Kiselev