Add matching of select to formal arguments of the function to cite …

…when `type = "param"` or `type = "dot_params"`. Also conform multiple aspects of the package for the compliance of CRAN submission.

DESCRIPTION

@@ -1,21 +1,22 @@
 Package: roclang
-Title: Helper Functions to Cite and Diffuse R Functions' Documentations
+Title: Functions for Diffusing Function Documentations into 'Roxygen' Comments
 Version: 0.1.0
 Authors@R: 
     person(given = "Xiurui",
            family = "Zhu",
            role = c("aut", "cre"),
            email = "zxr6@163.com",
            comment = NULL)
-Description: roclang package, like rlang package, dedicates itself to diffusing content to facilitate more efficient programming. But unlike rlang, which works on diffusing R code, roclang works on diffusing 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 roxygen2 documentation of another function by inserting inline code. 
+Maintainer: Xiurui Zhu <zxr6@163.com>
+Description: 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. 
 License: MIT + file LICENSE
 Suggests: 
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Encoding: UTF-8
-LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.1.1
+Depends: R (>= 4.0.0)
 Imports: 
     dplyr (>= 1.0.2),
     tidyr (>= 1.1.2),
@@ -25,4 +26,7 @@ Imports:
     magrittr (>= 2.0.1),
     rlang (>= 0.4.10),
     roxygen2 (>= 7.1.1),
+    methods (>= 4.0.0),
     rex (>= 1.2.0)
+URL: https://github.com/zhuxr11/roclang
+BugReports: https://github.com/zhuxr11/roclang/issues

NAMESPACE

@@ -9,6 +9,7 @@ import(tibble)
 import(tidyr)
 importFrom(magrittr,"%>%")
 importFrom(magrittr,"%T>%")
+importFrom(methods,formalArgs)
 importFrom(rex,escape)
 importFrom(rlang,parse_expr)
 importFrom(roxygen2,rd_roclet)

R/roc_functions.R

@@ -6,8 +6,10 @@ NULL
 #'
 #' \code{extract_roc_text} cites sections or parameters from a function documentation
 #' in the syntax of \code{@inherit}, \code{@inheritSection}, \code{@inheritParams} or \code{@inheritDotParams} tag
-#' from \code{\link[roxygen2]{rxoygen2}} package. See details about how to use this function.
+#' from \code{\link[roxygen2]{roxygen2}} package. See details about how to use this function.
 #'
+#' @importFrom methods formalArgs
+#' @importFrom rlang parse_expr
 #' @importFrom roxygen2 roc_proc_text rd_roclet
 #'
 #' @param fun Function or character indicating function name.
@@ -70,6 +72,8 @@ extract_roc_text <- function(
         stop("select should be length 1 for type = ", type)
       } else if (stringr::str_detect(select, " ") == TRUE) {
         stop("select should contain no spaces since only 1 is allowed for type = ", type)
+      } else if (identical(stringr::str_trim(select), "") == TRUE) {
+        stop("select should not be blank for type = ", type)
       } else {
         select
       }
@@ -86,6 +90,32 @@ extract_roc_text <- function(
     dot_params = paste(select, collapse = " "),
     stop("type not supported as: ", type)
   )
+  # Check whether the selected parameter is one of the formalArgs of fun
+  fun_function <- eval(rlang::parse_expr(fun))
+  if (type %in% "param" == TRUE) {
+    if (identical(select, "...") == TRUE) {
+      stop("cannot select '...' for type = 'param'; ",
+           "use type = 'dot_params' instead")
+    } else if (select %in% methods::formalArgs(fun_function) == FALSE) {
+      stop("select = ", select, " does not match any of methods::formalArgs(", fun, ")")
+    }
+  } else if (type %in% "dot_params" == TRUE) {
+    if (identical(select, "...") == TRUE) {
+      stop("cannot select '...' for type = 'dot_params'")
+    } else {
+      # Get positive selection(s)
+      select_pos <- select %>%
+        paste(collapse = " ") %>%
+        stringr::str_split(" ") %>%
+        purrr::pluck(1L) %>%
+        stringr::str_subset("^-", negate = TRUE)
+      select_pos_lgl <- select_pos %in% methods::formalArgs(fun_function)
+      if (any(select_pos_lgl == FALSE)) {
+        stop("select = c(\"", paste(select_pos[select_pos_lgl == FALSE], collapse = "\", \""),
+             "\") does not match any of methods::formalArgs(", fun, ")")
+      }
+    }
+  }
 
   # Format a Roxygen2 function blocks
   roxygen_fun_text <- .assemble_text_fun(fun = fun, type = type, select = select)
@@ -216,8 +246,8 @@ extract_roc_text <- function(
 #'
 #' @inheritParams roxygen2::roc_proc_text
 #'
-#' @return List with names as \code{fun_name.Rd}, where each element is the Rd text for
-#' the corresponding function, same as \code{\link[roxygen2]{roc_proc_text}}.
+#' @return List with names as \code{fun_name.Rd}, where each element is the \code{\link[roxygen2]{RoxyTopic}} for
+#' the corresponding function, same as the return of \code{\link[roxygen2]{roc_proc_text}}.
 #'
 #' @note Change log:
 #' \itemize{

README.Rmd

@@ -16,7 +16,7 @@ knitr::opts_chunk$set(
 # Diffusing roxygen documentation content with roclang
 
 <!-- badges: start -->
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html)
 [![CRAN status](https://www.r-pkg.org/badges/version/roclang)](https://CRAN.R-project.org/package=roclang)
 <!-- badges: end -->
 
@@ -135,7 +135,7 @@ roc_eval_text(roxygen2::rd_roclet(), fun_text)[[1L]]
 
 ## Further possibilities
 
-Since `roclang` returns Rd text, which is by nature character, 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.
+Since `extract_roc_text()` returns Rd text, which is by nature of type "character", 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
 

README.md

@@ -6,13 +6,13 @@
 <!-- badges: start -->
 
 [![Lifecycle:
-experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html)
 [![CRAN
 status](https://www.r-pkg.org/badges/version/roclang)](https://CRAN.R-project.org/package=roclang)
 <!-- badges: end -->
 
 **Package**: roclang<br /> **Authors**: Xiurui Zhu<br /> **Modified**:
-2021-08-03 09:52:36<br /> **Compiled**: 2021-08-03 09:52:43
+2021-08-03 12:36:36<br /> **Compiled**: 2021-08-03 14:24:58
 
 The goal of `roclang` is to diffuse documentation content to facilitate
 more efficient programming. As a partner of
@@ -351,11 +351,13 @@ roc_eval_text(roxygen2::rd_roclet(), fun_text)[[1L]]
 
 ## Further possibilities
 
-Since `roclang` returns Rd text, which is by nature character, 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.
+Since `extract_roc_text()` returns Rd text, which is by nature of type
+“character”, 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
 

man-roxygen/ex-extract_roc_text.R

@@ -1,21 +1,37 @@
 # Inherit a standard section, and leave the first letter as is
-cat(extract_roc_text(stats::lm, type = "general", select = "description", capitalize = NA))
+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))
+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)
+    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)
+    extract_roc_text(stats::lm,
+                     type = "dot_params",
+                     select = c("-formula", "-data"),
+                     capitalize = FALSE)
   )
 )

tests/testthat/test-extract_roc_text.R

@@ -0,0 +1,37 @@
+library(testthat)
+library(stringr)
+
+test_that("extract_roc_text extracts parts of a function documentation", {
+  expect_match(extract_roc_text(stats::lm, "general", "title", NA),
+               "^Fitting Linear Models$")
+  expect_match(extract_roc_text(stats::lm, "general", "description", NA),
+               "^\\\\code\\{lm\\} is used to fit linear models\\.")
+  expect_match(extract_roc_text(stats::lm, "general", "return", NA),
+               "^\\\\code\\{lm\\} returns an object of")
+  expect_match(extract_roc_text(stats::lm, "general", "author", NA),
+               "^The design was inspired by")
+  expect_match(extract_roc_text(stats::lm, "general", "references", NA),
+               "^Chambers, J\\. M\\. \\(1992\\)")
+  expect_match(extract_roc_text(stats::lm, "general", "examples", NA),
+               "^require\\(graphics\\)")
+  expect_match(extract_roc_text(stats::lm, "section", "Using time series", NA),
+               "^Considerable care is needed when using")
+  expect_match(extract_roc_text(stats::lm, "param", "formula", NA),
+               "^an object of class")
+  expect_match(extract_roc_text(stats::lm, "dot_params", "formula data", NA),
+               "^Arguments passed on to")
+  expect_match(extract_roc_text(stats::lm, "dot_params", c("-formula", "-data"), NA),
+               "^Arguments passed on to")
+})
+
+test_that("extract_roc_text sets capitalization", {
+  expect_match(extract_roc_text(stats::lm, "general", "title", TRUE),
+               "^Fitting Linear Models$")
+  expect_match(extract_roc_text(stats::lm, "general", "title", FALSE),
+               "^fitting Linear Models$")
+  # Capitalization should not work on non-letter characters, e.g. \\
+  expect_match(extract_roc_text(stats::lm, "general", "description", TRUE),
+               "^\\\\code\\{lm\\} is used to fit linear models\\.")
+  expect_match(extract_roc_text(stats::lm, "general", "description", TRUE),
+               "^\\\\code\\{lm\\} is used to fit linear models\\.")
+})

tests/testthat/test-roc_eval_text.R

@@ -0,0 +1,16 @@
+library(testthat)
+library(stringr)
+
+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
+'
+test_that("roc_eval_text parses diffused roxygen comments to Rd text", {
+  expect_true(roc_eval_text(roxygen2::rd_roclet(), fun_text)[[1L]]$is_valid())
+})