Documenting Functions

Documenting Functions

Functions should be well-documented to ensure they are understandable and easy to use. See Roxygen2 for more information on function style conventions.

Function Header

Each function should have a header that describes the function's purpose, its inputs (parameters), and the expected output:

Component	Description
Title	A brief, descriptive title of the function that summarizes its purpose.
Description	A short explanation of what the function does, including the primary task or transformation it performs.
@param	A description of each parameter (argument) the function accepts. It should include the parameter name, its type, and what it represents or does.
@return	A description of what the function returns, specifying the type of the returned object and what information or result it holds.
@example	A reproducible example showing how to use the function, including input data, the function call, and expected output. This helps users understand how to apply the function.

Function body

The function body contains the code that implements the function. Each major step in the code should include a numbered comment explaining its purpose. This helps users understand the function and makes debugging easier.

Recommended structure for a function:

#' [Title of the Function]
#'
#' [Brief description of what the function does]
#'
#' @param [param_name] [Type and description of the parameter]
#' @param [param_name] [Type and description of the parameter]
#' @param [param_name] [Type and description of the parameter]
#' @return [Description of the return value or object]
#' 
#' @example # Example usage of the function
#' [Example data]
#' [Example function call]
#' [Example result printing]
[function_name] <- function([param1], [param2], 
                            [param3] = [default_value], 
                            [param4]) {
  # [Step 1: Description of what this step does]
  [code for step 1]
  
  # [Step 2: Description of what this step does]
  [code for step 2]
  
  # [Step 3: Description of what this step does]
  [code for step 3]
  
  # [Step 4: Description of what this step does]
  [code for step 4]
  
  # [Step 5: Description of what this step does]
  [code for step 5]
  
  return([result])
}