Using Roxygen2 Template Tags

Using Roxygen2 Template tags

Perfect! Thanks @hadley. The GitHub version of plyr was the perfect example.

I will describe the process here for future overflowers.

Using Templates with Roxygen2

1) You should create a folder to hold your templates: man-roxygen/

2) Each template is a .R file that lives in man-roxygen/

For example: man-roxygen/someTemplate.R

 #' ... [other roxygen2 tags and information] ...
 #'
 #' @param someParm A parameter that is used in several functions.
 #'
 #' ... [more roxygen2 tags and information] ...

3) Now in some other roxygen2 block you can call all of that roxygen2 code this way.

 #' ... [other roxygen2 tags and information] ...
 #'
 #' @template someTemplate

4) When you use the template you get everything in the someTemplate.R file.

Check out the plyr package on GitHub to see the clever way Hadley uses several template files stored in man-roxygen\ that he can mix and match to create the documentation. Look at the following to get the idea:

Look for the use of @template in these files:

 R/aaply.r
 R/adply.r

Look at the templates here:

 man-roxygen/ply.r
 man-roxygen/a-.r
 man-roxygen/-a.r
 man-roxygen/-d.r

Use Roxygen2 template tags in references section

I think I've established that what I want to do is impossible. The Roxygen manual states that

Templates must be composed of complete tags - because all roxygen tags are current block tags, they can not be used for inline insertions.

An alternative is to use Rdpack: see Citing articles using roxygen2

Location of files when using @example tag with roxygen2

The appropriate location for examples used in your roxygen is:

inst/examples/

The roxygen line then should be:

#' @example inst/examples/add.R

---

Is this good practice? I think it is, since:

• It makes it easier to run, modify and test the examples whilst developing
• It makes it possible (in principle, at least) to re-use the examples in different places in the documentation, e.g. in the vignette

Use roxygen2 to generate namespace: a small example or template

Try to create a function within the R folder of you package.

Something like

#' Function to plot something
#' 
#' @param my_data a data frame
#' @param x column name for x axis
#' @param y column name for y axis
#' @export
#' @import ggplot2
#' @examples
#' plotSomething(iris, 'Sepal.Length', 'Sepal.Width') 
plotSomething <- function(my_data, x, y) {
  ggplot(my_data, aes_string(x=x, y=y)) + geom_point()
}

The keywords @export and @import will be parsed by roxygen2 and will update the NAMESPACE file after using devtools::document().

CRAN note when using roxygen2 template

You need to add man-roxygen to the .Rbuildignore file. See the plyr package and how it has done this here. And this post on SO might also be useful.

How to not run an example using roxygen2?

Use \dontrun{}

#'@examples
#'\dontrun{
#'geocode("3817 Spruce St, Philadelphia, PA 19104")
#'geocode("Philadelphia, PA")
#'dat <- data.frame(value=runif(3),address=c("3817 Spruce St, Philadelphia, PA 19104","Philadelphia, PA","Neverneverland"))
#'geocode(dat)
#'}

---

Related Topics