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

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

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?

Solution

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