This vignettes contains hints and recommendations for writing R functions within a package. If you are not already comfortable with writing R functions, you can read the chapters from R for data science and Advanced R.
Your R function must be contained in a .R file under the R folder. As
a rule, one R script contains only one function. If you have functions
that are closely related, such as a function returning an S3 object and
associated S3 methods, it can make sense to have them all in the same
script. We recommend combining functions that share common
documentation. Combining the documentation of multiple functions is
achieved using the roxygen2 tag @rdname.
When writing an R function, you will likely call functions from other
packages. You may be used to calling library() or
require() to load the namespace of a package and attach it
to the search path. Never do this when writing package functions, as
dependencies are handles elsewhere. Specifically, the DESCRIPTION file
contains an imports field, listing all external packages needed for our
package to work. Packages listed here will be installed when EpiForsk is
installed. To add a package to the imports, use
usethis::use_package(). Note the packages added to the
description file are not imported into the EpiForsk package. The imports
field just ensures the packages are present on the users computer. To
use functions from external packages, use the :: operator.
Writing pkg::name will load package pkg if it
isn’t already loaded and access the function name. It is
possible to import functions from other packages into the EpiForsk
namespace using @importFrom for a single function or
@import for the full package. It must be added to the
roxygen2 documentation in the EpiForsk_package.R file.
Doing this makes the imported functions part of the package, increasing
the chance of conflicting function names as well as increasing the
package size. Therefore :: is the default way to use
external functions. We recommend using @importFrom for
operators with special syntax such as %>% and for
functions used repeatedly. Calling :: costs around 5 μs, so
repeatedly means when the function could potentially be called millions
of times. We recommend avoiding @import. For more, see dependencies.
To test your function during development, you can use
devtools::load_all() to make it available in the R session.
This makes testing smoother than waiting for the package to install
every time.