Setting up a new {box} module with {roxygen2} comments

Question

I'm new to both {box} and {roxygen2} and have never written a package - so please bear with me. I've got a script that has a smallish function in it which I've verified works at my end. It's sited in a bespoke folder I've created, called R, inside the 'package' folder, e.g. 'Module1/R/functionscript1.R'. The script contains all the bits of {roxygen2} commenting that I think I need, including #' @export. I can't quite figure out the next stages despite reading many blogs. How do I turn this into a fully documented {box} module?

I've tried setting my working directory to the Module1 directory then using devtools::document(), which errors out telling me it can't find the package root (" Is . inside a package?"). No version of box::use() is doing anything I think it should. What am I missing?? Please explain like I'm a toddler.....

Thanks

Answer 1

With ‘box’, there’s no need to call devtools::document(). And in fact you can see from the error message that it doesn’t work.

Writing your documentation comment inside the module is all that’s required. When you now load the module you can display its documentation.

Let’s say your Module1/R/functionscript.R looks like this:

#' Some test function
#' @param n a number
#' @return the modified number
#' @export
modify = function (n) {
  n * 2 - 1
}

Then you can load your module (note that having R in the directory name is a bit weird when working with modules, since it will become part of the module name):

box::use(./Module1/R/functionscript)

After loading the module you can use it:

functionscript$modify(5)
# [1] 9

And you can display its documentation via box::help:

box::help(functionscript$modify)

And this will display the help, e.g.: