How to display the elements of a returned list in Roxygen?

Question

I can do this easily with input parameters by having multiple lines of @param by doing as such:

#' @param var1 This is for x
#' @param var2 This is for y
#' @param var3 This is for Z

But how do you do that for the elements of a list you are returning. I want to include the names of each element and a description about them. Chaining together @return or @param does not have the same behavior. What is the appropriate tag?

#' @return A list with the following elements:
#' @something element1 Contains x
#' @something element2 Contains y
#' @something element3 Contains z

The package samr has the exact markdown formatting I'm looking for:

Threesome

Answer 1

From the documantation - http://r-pkgs.had.co.nz/man.html#text-formatting

@return Used to document the object returned by the function. For lists, use the \item{name a}{description a} describe each component of the list.

Keshiakesia

That did it. I was using \itemize and that was changing the formatting. – Threesome

Answer 2

Since the link was broken in the accepted answer, I included a simple example of roxygen documentation for a function that provides a list as a return value.

#' Sample function that returns a list and uses roxygen documentation.
#'
#'
#' @return A list with letters and numbers.
#' \itemize{
#'   \item A - The letters of the alphabet.
#'   \item B - A vector of numbers.
#' }
myfunction <- function() {
  list(
    A = LETTERS,
    B = 1:10
  )
}

Assuming your package is called mypackage, the above facilitates producing documentation similar to the output below when running ?mypackage::myfunction.

This was based on the link to R packages - Object Documentation - Text formatting reference sheet

Probe

The lists will not be aligned nicely, if the items are in different length. item{name a}{description a} is better in that case. – Rectory

@Rectory Thanks, I will add that option when I have a little more time to test my solution. – Probe