roclang: A package for diffusing function documentations into 'roxygen' comments

Description

The 'roclang' package facilitates efficient diffusing of content across function documentations. Sections, parameters or dot parameters are extracted from function documentations and turned into valid Rd character strings, which are ready to diffuse into the 'roxygen' comments of another function by inserting inline code.

Functions

• Text extraction and manipulation function: extract_roc_text.

• Rd evaluation and compilation function: roc_eval_text.

Note

Change log:

• 0.1.1 Xiurui Zhu - Initiate the document.

Author(s)

Xiurui Zhu

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

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)
  )
)

Generate Rd from text with evaluated inline code and code blocks

Description

roc_eval_text is an upgraded version of roc_proc_text that evaluates inline and block code before generating Rd.

Usage

roc_eval_text(roclet, input)

Arguments

Value

List with names as fun_name.Rd, where each element is the RoxyTopic for the corresponding function, same as the return of roc_proc_text.

Note

Change log:

• 0.1.0 Xiurui Zhu - Initiate the function.

Author(s)

Xiurui Zhu

Examples

# Formulate a text version of a function with documentation
fun_text <- '
#\' \\code{iris} is a `r nrow(iris)`-row matrix.
#\'
#\' \\code{iris} matrix has
#\' ```{r results="hold"}
#\' ncol(iris)
#\' ```
#\' columns.
print_iris <- function() iris
'

# Parse the 'roxygen' comments to Rd documentation
roc_eval_text(roxygen2::rd_roclet(), fun_text)[[1L]]