r - Using Roxygen2 Template tags

Question

Could someone provide an example of how to properly use the Template Tags in Roxygen2. I have tried to do the most obvious thing (to me):

In my packageName-package.R file:

 #' [... other Roxygen blocks ...]
 #' 
 #' @templateVar testTemplateTag Testing one two
 NULL

Then in a file someFunction.R

 #' [... other Roxygen blocks ...]
 #'
 #' @template testTemplateTag

I get the error:

 Error : Can not find template testTemplateTag

I am trying to have one place to document commonly repeated definitions examples etc. When these things are nested within a set of functions I have been using @inheritParms. But some things, like definitions and and other descriptions, are used in several places. I've searched high and low for usage of @template and @templateVar and have not found anything.

Thanks.

Answer 1

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