Generate items with multiple arguments in an R documentation via roxygen2

Question

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

Answer 1

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).

Answer 2

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.