Generate items with multiple arguments in an R documentation via roxygen2

10
votes

To generate an R documentation file (.Rd) I use the package RStudio/Document option with R 3.0.2, Linux 3.11, devtools 1.5, roxygen2 4.0.1.

Objective

I want to describe multiple arguments of a function in the documentation file, such as in this example:

\arguments{
  \item{arg1, arg2}{Description}
}

Here, the arguments arg1 and arg2 are split by a space character. This leads to an automatic line break in the HTML version.

Problem

Using the RStudio/Document option, a space between the two arguments puts the second one in the 'Description' part, e.g.:

#' @param arg1, arg2 Description

will become

\arguments{
  \item{arg1,}{arg2 Description}
}

Inappropriate Solution

The only way I figured out to keep both arguments inside the 'argument' part is by not splitting by a space, e.g.:

#' @param arg1,arg2 Description

will become

\arguments{
  \item{arg1,arg2}{Description}
}

This is not wanted since with a greater amount of arguments the 'column' with the argument use a lot of space. I tried to escape the space with \ or \\ as well as to inlcude all arguments with \code{...}, but none of it worked as desired.

Question

Is there a way to create an output as in my Objective? Maybe some escape character that introduce a space?

Thank you.
Sven

2
rdevtoolsroxygen2roxygenrd
It's the roxygen2 package that is generating the man pages, not devtools. - Richie Cotton
So devtools uses roxygen2? - setempler
Yes. If you look at packageDescription("devtools"), you'll see that roxygen2 is in the "Suggests" section. That means that roxygen2 is used but devtools, but it isn't compulsory for using it. (For example, you can use devtools but manually write your documentation, in which case, you won't need roxygen2.) - Richie Cotton
Thanks, clarified that in my question. - setempler

2 Answers

8
votes

It now seems to work with roxygen2 6.0.1:

#' @param arg1,arg2 Description

(no space after comma) gives

\arguments{
  \item{arg1, arg2}{Description}
}

(with space after comma).

5
votes

I haven't found a way to persuade roxygen2 to let you generate the line with a space between the arguments, but you can always manually update the Rd file after you call roxygenize.

library(stringr)
filename <- "your package root/man/your_function.Rd"
lines <- readLines(filename)
lines <- str_replace(lines, fixed("\item{arg1,arg2}"), "\item{arg1, arg2}")
writeLines(lines, filename)

Of course, documenting several things in one go is potentially confusing for the reader. It's almost alway better to stick to the convention of one argument description per line, since that is what the reader expects.