When documenting in Roxygen: How do I make an itemized list in @details?

Question

What is the appropriate syntax to add an itemized list to roxygen2, for instance, in the @details section? Can I create a latex list environment?

It seems that line breaks are simply ignored, i.e.

#' @details text describing parameter inputs in more detail
#'
#' parameter 1: stuff
#' 
#' parameter 2: stuff

thanks!

Kramer

do \describe{}, \itemize{} as in the R extensions manual work ... ? – Vuong

Answer 1

Here is a roxygen2 example following your problem formulation.

##'
##' @details text describing parameter inputs in more detail.
##' \itemize{
##'  \item{"parameter 1"}{Stuff}
##'  \item{"parameter 2"}{Stuff}
##' }
##'

This will allow you to use itemize in details section. You can also use it in the @param sections.

Hope this helps.

Urania

Can you point me to the documentation where you found this? I'm having a hard time figuring out the syntax for some of the Latex features in Roxygen. – Unopened

@JeffAllen I just looked through the cran.r-project.org/doc/manuals/R-exts.html#Lists-and-tables section of the "Writing R Extensions" manual and tried it in Roxygen, which works fine for me. Is there a specific problem you're having? – Urania

@JeffAllen Note that this is just the standard R doc (.Rd) style for lists, which is just the LaTeX style. Trouble with both roxygen and .Rd is that it can be hard to predict when something that works in tex will work in .Rd, and when what works in .Rd will work in roxygen... – Kramer

This works for me, except that the args for \item are just written out as-is without formatting. Note: no space between \itemize and "{". – Graber

I think you mean \describe{...}, not \itemize{...}. \describe takes a named parameter and a definition, \itemize is just a bulleted list. – Wilburnwilburt

The quotes are not strictly necessary, you can still show the items without them. I would also add a space between {"parameter 1"} and {Stuff}, as in {"parameter 1"} {Stuff} – Pesthole

Answer 2

Since roxygen2 6.0.0 you can use markdown directly in your R documentation.

#' @details text describing parameter inputs in more detail.
#' * parameter 1 stuff
#' * parameter 2 stuff
#' @md

To use this either include Roxygen: list(markdown = TRUE) in your description to turn markdown on for the whole package or add the @md tag to a single file.

Waugh

Documentation: Write R documentation in Markdown by Gábor Csárdi. "Note that you do not have leave an empty line before the list. This is different from some markdown parsers." – Zaccaria

The link is dead, the new vignette can be found here – Brokendown