Roxygen2: document a function with an optional parameter

Question

What is the correct way of roxygen documenting a function with an optional parameter like

#' @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)
}

In particular how should one comment on the optional parameters chambers and hgt ?

Answer 1

I would just add a @param field for each argument and explicitly write if an argument is optional, like this:

#' @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)
}

If your user reads docs, then he/she would know that these arguments are optional. If not, he/she will figure it out experimentally by omitting these arguments.

Hope this helps.

PS Good R coding practice requires you to document each and every function argument. If you don't do this, Roxygen2 would issue warnings during the package check.