extract_roc_text {roclang}

Extract a section, parameter or set of dot-parameters from a function documentation

Description

extract_roc_text cites sections or parameters from a function documentation in the syntax of @inherit, @inheritSection, @inheritParams or @inheritDotParams tag from roxygen2 package. See details about how to use this function.

Usage

extract_roc_text(
  fun,
  type = c("general", "section", "param", "dot_params"),
  select = NULL,
  capitalize = NA
)

Arguments

fun

Function or character (of length 1L) indicating function name.

type

Type of extraction. Please choose one from the following table according to the @tag you would otherwise use if you would like to inherit the section, parameter or set of dot-parameters as a whole:

@tag you would use	type you should choose
@inherit	"general"
@inheritSection	"section"
@inheritParams	"param"
@inheritDotParams	"dot_params"

select

Selection of extraction based on type.

type = "general"

Character (of length 1L) indicating the section to extract

type = "section"

Character (of length 1L) indicating the section title to extract

type = "param"

Character (of length 1L) indicating the name of parameter to extract

type = "dot_params"

Character (of length 1L) or character vector to add or remove (with "-") parameters as @inheritDotParams; if character vector provided, the elements are concatenated with spaces just as @inheritDotParams syntax, e.g. "x y" to inherit two parameters, "-z" to remove a parameter or c("-x", "-y") to remove two parameters

capitalize

Logical (of length 1L) indicating whether the first letter of the return should be capitalized. Default to capitalize = NA, in which case the first letter of the return is left as is.

Details

To diffuse the function output into roxygen2 comments, one may write the function documentation with inline code like this:

#' Diffusion of function documentation with inline code
#'
#' @return Same as \code{\link[stats]{lm}}:
#' `r extract_roc_text(stats::lm, type = "general", select = "return")`
my_fun <- function() {}

or with code block like this:

#' Diffusion of function documentation with code block
#'
#' @param lm_arg Named list of
#' ```{r}
#' extract_roc_text(stats::lm,
#'                  type = "dot_params",
#'                  select = c("-formula", "-data"),
#'                  capitalize = FALSE)
#' ```
my_fun <- function(lm_arg) {}

Value

Character (of length 1L) as a valid Rd character string to diffuse into roxygen2 comments.

Note

Change log:

• 0.1.0 Xiurui Zhu - Initiate the function.

• 0.1.1 Xiurui Zhu - Change the default of capitalize from TRUE to NA.

• 0.1.1 Xiurui Zhu - Improve code security in evaluating the formal arguments of fun.

• 0.2.0 Xiurui Zhu - Make changes for roxygen2 > 7.1.2 while keeping compatibility.

Author(s)

Xiurui Zhu

Examples

# Inherit a standard section, and leave the first letter as is
cat(
  extract_roc_text(stats::lm,
                   type = "general",
                   select = "description",
                   capitalize = NA)
)

# Inherit a self-defined section, and capitalize the first letter
cat(
  extract_roc_text(stats::lm,
                   type = "section",
                   select = "Using time series",
                   capitalize = TRUE)
)

# Inherit a parameter, and diffuse it into text
cat(
  paste0(
    "Here is the `formula` argument of `stats::lm`, defined as: ",
    extract_roc_text(stats::lm,
                     type = "param",
                     select = "formula",
                     capitalize = FALSE)
  )
)

# Inherit a set of dot params, and diffuse it into text
cat(
  paste0(
    "`lm_arg` is a named list of ",
    extract_roc_text(stats::lm,
                     type = "dot_params",
                     select = c("-formula", "-data"),
                     capitalize = FALSE)
  )
)