R function documentation with roxygen2 - single function

roxygen2OneFunction.gist.R

#=====================================
# Demo function roxygen2 documentation
#=====================================
 
# This shows how things work, including weird corner cases, not how they
# should be done. Most of the information comes from
#    http://r-pkgs.had.co.nz/man.html
 
 
#' Brief description/title of the page describing this function.
#'
#' This is the introductory (Description paragraph in the documentation, comes
#' before everything else and auto-wraps. Must be separated by a
#' blank comment line from the title (Not a REAL blank line).
#'
#' This is the Details section that comes after usage. This and any following
#' paragraphs without @@section labels are part of the Details section.
#'
#' This is a second paragraph in the Details section.
#' @section Some section:
#' This is the first paragraph in the section "Some section".
#' Any further paragraphs will also be in some section, up until a new
#' @@roxygen2_tag. Note: no blank lines are needed before a tag. Also note
#' that the colon is required.
#'
#' This is a new paragraph.
#'
#' @section Final section:
#'
#' Shows that skipping lines between tags and text, or skipping multiple lines
#' between paragraphs makes no difference.
#'
#'
#'
#' See? Note: All Description generally should come before the
#' specific function tags as they are more reasonably placed just before the
#' function definition.
#'
#' @param x Can describe sequentially if only need short descriptions.
#' @param y The value to return. This description appears under the Arguments
#'    section. Can be multiple paragraphs if needed.
#'
#'    Still describing param y here. Indenting for tags that might be only on
#'    one line makes them more readable, bur doesn't necessarily translate to
#'    to the generated documentation.
#' @param z
#'    Can describe on another line only, but probably still want to indent.
#' @return This describes what the function returns. May be multiple lines
#'    and multiple paragraphs. Becomes the Values section.
#' @examples
#' x <- 0
#' \dontrun{
#' x <- c(
#'   "Only indent examples if want the example R code to be indented.",
#'   "One weird thing, the \dontrun command's layout is weird.",
#'   "The opening tag appears exctaly where the command starts.",
#'   "The following code is then laid out normally,",
#'   "The ending don't run tag has an extra newline before it.",
#'   "So to prevent extra blank line inside norun blocks...",
#'   "End with closing brace at end of last code line."
#' ) }
#' y <- "1"
#' z <- "2"
#' foo(x, y, z)
foo <- function(x, y, z) {
   return(c(x, y, z));
}