31.4 Importing Functions: Use Roxygen

PEcAn style is to import very few functions and instead use fully namespaced function calls (pkg::fn()) everywhere it’s practical to do so. In cases where double-colon notation would be especially burdensome, such as when importing custom binary operators like %>%, it’s acceptable to import specific functions into the package namespace. Do this by using Roxygen comments of the form #' @importFrom pkg function, not by hand-editing the NAMESPACE file.

If the import is only used in one or a few functions, use an @importFrom in the documentation for each function that uses it. If it is used all over the package, use a single @importFrom in the Roxygen documentation block for the whole package, which probably lives in a file called either zzz.R or <your_package_name>-package.R:

#' What your package does
#'
#' Longer description of the package goes here.
#' Probably with links to other resources about it, citations, etc.
#'
#' @docType package
#' @name PEcAn.yourpkg
#' @importFrom magrittr %>%
NULL

Roxygen will make sure there’s only one NAMESPACE entry per imported function no matter how many importFrom statements there are, but please pick a scheme (either import on every usage or once for the whole package), stick with it, and do not make function x() rely on an importFrom in the comments above function y().

Please do not import entire package namespaces (#' @import pkg); it increases the chance of function name collisions and makes it much harder to understand which package a given function was called from.

A special note about importing functions from the tidyverse: Be sure to import from the package(s) that actually contain the functions you want to use, e.g. Imports: dplyr, magrittr, purrr / @importFrom magrittr %>% / purrr::map(...), not Imports: tidyverse / @importFrom tidyverse %>% / tidyverse::map(...). The package named tidyverse is just a interactive shortcut that loads the whole collection of constituent packages; it doesn’t export any functions in its own namespace and therefore importing it into your package doesn’t make them available.