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？

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

如果您的用户阅读文档，那么他/她就会知道这些参数是可选的。如果没有，他/她将通过省略这些参数来通过实验找出答案。

希望这可以帮助。

PS良好的 R 编码实践要求您记录每个函数参数。如果您不这样做，Roxygen2 将在包检查期间发出警告。