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?

Luxuriate

I'm not sure I understand...add @param entries for them...? – Peluso

and leave out the @usage – Kassab

Well the point is that the two parameters hgtand chambersare inherently different from the others in the sense that they are optional. One of them is set to TRUE while the other calls an external function. What is the correct way to inform the reader of the documentation about this? – Luxuriate

I agree with the answer by @R Kiselev . Probably most of the parameters in most of the built-in functions in R are optional, in the sense that the user doesn't need to touch them, unless they have reason to. In the function definition, the default values of these can be set to FALSE or NULL. E.g. Fun = function(data, weights=NULL, adjust=FALSE, verbose=FALSE, plot.it=TRUE){. In the @param and @details sections, you add as much description as is necessary for the user to understand and use the function correctly. – Belle

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.

P.S. 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.

Lemberg