User manual

Chapter 10: Developing with ESS 52

10.2.2 Editing Roxygen documentation

The Roxygen R package makes it possible to keep the intended contents for Rd ﬁles as

structured comments in the R source ﬁles. Roxygen can then parse R ﬁles and generate ap-

propriate Rd ﬁles from these comments, ﬁll the usage ﬁelds as well as updating ‘NAMESPACE’

ﬁles. See the Roxygen documentation found via http://roxygen.org for more information

on its usage. An example of an Roxygen entry for a simple R function can look like this:

##’ Description of the function

##’

##’ Further details about this function

##’ @title A title

##’ @param me all parameters must be listed and documented

##’ @return Description of the return value

##’ @author The author

myfun <- function(me)

cat("Hello", me, "\n")

The entry is immediately preceding the object to document and all lines start with the

Roxygen preﬁx string, in this case ##’. ESS provides support to edit these documentation

entries by providing line ﬁlling, navigation, template generation etc. Syntax highlighting is

provided for Emacs but not for XEmacs.

Roxygen is customized by the variables in the customization group “Ess Roxy”. Cus-

tomizables include the Roxygen preﬁx, use of folding to toggle visibility of Roxygen entries

and the Roxygen template.

All ESS Roxygen support is deﬁned in ‘ess-roxy.el’ which is loaded by default in ESS.

The following special Emacs commands are provided.

[Command]ess-roxy-update-entry

C-c C-o C-o Generate a Roxygen template or update the parameter list in Roxygen

entry at point (or above the function at the point). Documented parameters that are

not in the function are placed last in the list, parameters that are not documented

and not in the deﬁnition are dropped. Parameter descriptions are ﬁlled if ess-roxy-

fill-param-p is non-nil.

[Command]ess-roxy-toggle-roxy-region beg end

C-c C-o C-c Toggle the presence of the leading Roxygen string on all lines in the

marked region (between beg and end. Convenient for transferring text to Roxygen

entries and to evaluate example ﬁelds.

[Command]ess-roxy-preview-Rd name-file

C-c C-o C-r Use the attached R process to parse the entry at point to obtain the Rd

code. Convenient for previewing and checking syntax. When used with the preﬁx

argument name-ﬁle, i.e. C-u C-c C-e C-r, place the content in a buﬀer associated

with a Rd ﬁle with the same name as the documentation. Requires the Roxygen

package to be installed.

[Command]ess-roxy-preview-HTML visit-instead-of-open

C-c C-o C-t Use the attached R process to parse the entry at to generate HTML for

the entry and open it in a browser. When used with the preﬁx argument visit-instead-