in an R documentation file, how can I include a list in a subsection

Question

I have a some roxygen that works like this

#' @return
#' \subsection{foo} {
#'    \item{bar}{all about bar}
#' }

and R dies on this saying it doesn't know the macro \item. If I remove the subsection, it works.

#' @return
#'    \item{bar}{all about bar}

and this works.

Is there any way to get my bar item in the subsection?

I think all `\item`s need to be inside an `\itemize{}` grouping. — nrussell, Dec 01 '16 at 17:52
Hmm, they don't need to (because the second code block works to generate at itemized list) but you are right that it does make the \item work when it is inside the subsection block. — pdb, Dec 01 '16 at 19:10
Return is a special case - it's explicitly documented to accept bare items — hadley, Dec 02 '16 at 02:55
ah, under "\value{...}" here https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Documenting-functions you have an amazing memory. It is not documented later under lists and tables. — pdb, Dec 04 '16 at 03:24
Related, newer solution: https://stackoverflow.com/a/42812714 — Brandon Bertelsen, Feb 07 '20 at 03:28

score 0 · Accepted Answer · answered Oct 18 '18 at 15:43

In @return there is an implied \describe environment that the \subsection breaks.

This would work

#' @return
#' \subsection{foo} {
#'    \describe{
#'      \item{bar}{all about bar}
#'    }
#' }

See section 2.2.1, "Documenting Functions" in https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Documenting-functions under \value{…} which reads, "Note that \value is implicitly a \describe environment, so that environment should not be used for listing components, just individual \item{}{} entries."

1 Answers1