NAMESPACE tags

The package NAMESPACE is one of the most confusing parts of building a package. Roxygen2 aims to make it as easy as possible to build a package that is a well-behaved member of the R ecosystem. This is a little frustrating at first, but soon becomes second-nature.

Exports

For a function to be usable outside your package, you must export it. By default roxygen2 doesn’t export anything from your package. If you want an object to be publicly available, you must explicitly tag it with @export.

Use the following guidelines to decide what to export:

Specialised exports

Generally, roxygen2 can generate the correct namespace directive when @exporting a specific object. However, you may want to override the defaults and exercise greater control. In this case, you can use the more specialised tags described below:

For even more specialised cases you can use @rawNamespace code which inserts code literally into the NAMESPACE. If you need to automate this, @evalNamespace foo() will evaluate the foo() in the package environment and insert the results into NAMESPACE. Because evalNamespace() is run in the package environment, it can only generate exports, not imports.

Imports

The NAMESPACE also controls which functions from other packages are made available to your package. Only unique directives are saved to the NAMESPACE file, so you can repeat them as needed to maintain a close link between the functions where they are needed and the namespace file.

Importing functions

If you are using just a few functions from another package, the recommended option is to add the package name to the Imports: field of the DESCRIPTION file and call the functions explicitly using ::, e.g., pkg::fun().

my_function <- function(x, y) {
  pkg::fun(x) * y
}

If the repetition of the package name becomes annoying you can @importFrom and drop the :::

#' @importFrom pkg fun 
my_function <- function(x, y) {
  fun(x) * y
}

Imports affect every function in a package, so it’s common to collect them in a central place, like {packagename}-package.R.

#' @importFrom pkg fun1 fun2
#' @importFrom pkg2 fun3
#' @importFrom pkg3 fun4
NULL
#> NULL

Note the use of NULL here: you must provide something for roxygen2 to document, so we use NULL as place holder.

It is possible, but not generally recommended to import all functions from a package with @import package. This is risky if you import functions from more than one package, because while it might be ok today, in the future the packages might end up with a function having the same name, and your users will get a warning every time your package is loaded.

Beware

Be careful when mixing NAMESPACE directives with regular code. The following example won’t work because roxygen ignores empty lines in blocks. It will generate a namespace directive import(zoo, Different name for calling zoo.), which will error.

#' @import zoo

#' Different name for calling zoo.
#'
#' @params ... passed to zoo.
#' @return zoo object.
#'
#' @export 
zoo2 <- function(...) zoo(...)

Instead you need to add an explicit NULL:

#' @import zoo
NULL
#> NULL

#' Different name for calling zoo.
#'
#' @params ... passed to zoo.
#' @return zoo object.
#'
#' @export 
zoo2 <- function(...) zoo(...)

S3

If you’re adding a method to an S3 generic defined in another package, you must import it with @importFrom pkg generic. Otherwise roxygen2 can’t tell that your function is a method, and will not document it correctly.

S4

If you are using S4 you may also need:

Compiled code

To import compiled code from another package, use @useDynLib