README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

```{r, echo=FALSE}
roxygen_new <- utils::packageVersion("roxygen2") > "7.1.2"
```

# Diffusing 'roxygen' documentation content with 'roclang'

<!-- badges: start -->
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![CRAN status](https://www.r-pkg.org/badges/version/roclang)](https://CRAN.R-project.org/package=roclang)
[![R-CMD-check](https://github.com/zhuxr11/roclang/workflows/R-CMD-check/badge.svg)](https://github.com/zhuxr11/roclang/actions)
[![Codecov test coverage](https://codecov.io/gh/zhuxr11/roclang/branch/master/graph/badge.svg)](https://app.codecov.io/gh/zhuxr11/roclang?branch=master)
[![Download stats](https://cranlogs.r-pkg.org/badges/grand-total/roclang)](https://CRAN.R-project.org/package=roclang)
<!-- badges: end -->

**Package**: [*roclang*](https://github.com/zhuxr11/roclang) `r pkgload::pkg_version()`<br />
**Author**: Xiurui Zhu<br />
**Modified**: `r file.info("README.Rmd")$mtime`<br />
**Compiled**: `r Sys.time()`

The goal of `roclang` is to diffuse documentation content to facilitate more efficient programming. As a partner of [`rlang`](https://github.com/r-lib/rlang/), which works on diffusing R code, `roclang` works on diffusing ['roxygen'](https://github.com/r-lib/roxygen2/) 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' documentation of another function by inserting inline code.

## Installation

You can install the released version of `roclang` from [CRAN](https://cran.r-project.org/) with:

``` r
install.packages("roclang")
```

Alternatively, you can install the developmental version of `roclang` from [github](https://github.com/) with:

``` r
remotes::install_github("zhuxr11/roclang")
```

## Examples of diffusing content from other functions' documentations

These are some basic examples which show you how to diffuse sections (both general and self-defined) or parameters (including dot-parameters) from the documentation of another function, e.g. `stats::lm`:

```{r library, eval=FALSE}
library(roclang)
```

```{r, include=FALSE}
pkgload::load_all()
```

```{r example}
# 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 parameters, 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)
  )
)
```

```{r text-co-documentation, results='asis', include=roxygen_new, echo=FALSE}
cat(
  'When using `roxygen2 > 7.1.2`, the whole set of co-documented parameters should be selected to derive valid Rd documentation (see `news(package = "roxygen2")`). As is known from `?library`, parameters `package` and `help` are co-documented in function `library`:'
)
```

```{r example-co-documentation, include=roxygen_new, eval=roxygen_new, error=TRUE}
# You need to select the whole set of co-documented parameters
cat(
  extract_roc_text(library,
                   type = "param",
                   select = "package,help",
                   capitalize = NA)
)

# The order does not matter; character vector can also be used
cat(
  extract_roc_text(library,
                   type = "param",
                   select = c("help", "package"),
                   capitalize = NA)
)

# It will result in error if selecting only part of co-documented parameters 
cat(
  extract_roc_text(library,
                   type = "param",
                   select = "package",
                   capitalize = NA)
)

# Multiple parameters cannot be selected if independently documented
cat(
  extract_roc_text(library,
                   type = "param",
                   select = c("pos", "lib.loc"),
                   capitalize = NA)
)
```

## Use cases in 'roxygen' comments

In 'roxygen' comments, one can use inline code to diffuse the extracted content into his or her own documentations:

```{r example-roxygen-code}
#' Cited Version of \code{stats::lm} for
#' `r roclang::extract_roc_text(stats::lm, type = "general", select = "title", capitalize = TRUE)`
#'
#' Cited from \code{\link[stats]{lm}}:
#' `r roclang::extract_roc_text(stats::lm, type = "general", select = "description", capitalize = FALSE)`
#'
#' @importFrom stats lm
#' @importFrom rlang exec !!!
#'
#' @param formula Cited from \code{\link[stats]{lm}} with the same argument ame:
#' `r roclang::extract_roc_text(stats::lm, type = "param", select = "formula", capitalize = NA)`
#' @param df Cited from the argument `data` of \code{\link[stats]{lm}}:
#' `r roclang::extract_roc_text(stats::lm, type = "param", select = "data", capitalize = NA)`
#' @param lm_arg Named list of
#' `r roclang::extract_roc_text(stats::lm, type = "dot_params", select = c("-formula", "-data"), capitalize = FALSE)`
#'
#' @return `r roclang::extract_roc_text(stats::lm, type = "general", select = "return", capitalize = TRUE)`
#'
#' @note Copied by: Xiurui Zhu
#'
#' @examples
#' `r roclang::extract_roc_text(stats::lm, type = "general", select = "examples", capitalize = NA)`
lm_copy <- function(formula, df, lm_arg) {
  rlang::exec(stats::lm, formula = formula, data = df, !!!lm_arg)
}
```

To view the compiled Rd file, use `roc_eval_text()` function as an improved version of [`roxygen2::roc_proc_text()`](https://roxygen2.r-lib.org/reference/roc_proc_text.html) function, in that the former further evaluates inline code and code blocks before parsing the text into Rd.

```{r example-roxygen-compile}
# Formulate a text version of the function with documentation
fun_text <- '
#\' Cited Version of \\code{stats::lm} for
#\' `r roclang::extract_roc_text(stats::lm, type = "general", select = "title", capitalize = TRUE)`
#\'
#\' Cited from \\code{\\link[stats]{lm}}:
#\' `r roclang::extract_roc_text(stats::lm, type = "general", select = "description", capitalize = TRUE)`
#\'
#\' @importFrom stats lm
#\' @importFrom rlang exec !!!
#\'
#\' @param formula Cited from \\code{\\link[stats]{lm}} with the same argument name:
#\' `r roclang::extract_roc_text(stats::lm, type = "param", select = "formula", capitalize = NA)`
#\' @param df Cited from the argument `data` of \\code{\\link[stats]{lm}}:
#\' `r roclang::extract_roc_text(stats::lm, type = "param", select = "data", capitalize = NA)`
#\' @param lm_arg Named list of
#\' `r roclang::extract_roc_text(stats::lm, type = "dot_params", select = c("-formula", "-data"), capitalize = FALSE)`
#\'
#\' @return `r roclang::extract_roc_text(stats::lm, type = "general", select = "return", capitalize = TRUE)`
#\'
#\' @note Copied by: Xiurui Zhu
#\'
#\' @examples
#\' `r roclang::extract_roc_text(stats::lm, type = "general", select = "examples", capitalize = NA)`
lm_copy <- function(formula, df, lm_arg) {
  rlang::exec(stats::lm, formula = formula, data = df, !!!lm_arg)
}
'

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

## Further possibilities

Since `extract_roc_text()` returns Rd character strings, more *ad hoc* manipulations can be performed in the inline code using functions such as those from [`stringr`](https://github.com/tidyverse/stringr) package. This makes `roclang` even more flexible in diffusing 'roxygen' documentation content. With all manipulations settled, run `roc_eval_text()` to parse the 'roxygen' comments into Rd.

## Session info

This file was compiled with the following packages and versions:

```{r session-info}
utils::sessionInfo()
```