https://github.com/zhuxr11/roclang
A package that helps to diffuse 'roxygen' documentations.
https://github.com/zhuxr11/roclang
Last synced: 5 months ago
JSON representation
A package that helps to diffuse 'roxygen' documentations.
- Host: GitHub
- URL: https://github.com/zhuxr11/roclang
- Owner: zhuxr11
- License: other
- Created: 2021-08-02T16:09:26.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-05-27T03:27:58.000Z (almost 2 years ago)
- Last Synced: 2024-08-13T07:13:22.426Z (8 months ago)
- Language: R
- Homepage:
- Size: 129 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
- jimsghstars - zhuxr11/roclang - A package that helps to diffuse 'roxygen' documentations. (R)
README
---
output: github_document
---```{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'
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://CRAN.R-project.org/package=roclang)
[](https://github.com/zhuxr11/roclang/actions)
[](https://app.codecov.io/gh/zhuxr11/roclang?branch=master)
[](https://CRAN.R-project.org/package=roclang)**Package**: [*roclang*](https://github.com/zhuxr11/roclang) `r pkgload::pkg_version()`
**Author**: Xiurui Zhu
**Modified**: `r file.info("README.Rmd")$mtime`
**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()
```