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

Cyma

It's the roxygen2 package that is generating the man pages, not devtools. – Herbherbaceous

So devtools uses roxygen2? – Cyma

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

Thanks, clarified that in my question. – Cyma

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

Toor

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.

Herbherbaceous

Are there any news on this? Do you by any chance have filed an issue at the roxygen2 github? – Afreet

@Afreet I didn't file an issue, but feel free to submit one yourself. – Herbherbaceous