add tag methods for reusable examples

DESCRIPTION

@@ -36,8 +36,11 @@ Imports:
     usethis,
     withr
 Suggests:
+    brio,
+    roxygen2,
     rstudioapi,
     shinytest2,
+    stringr,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Config/testthat/parallel: true

NAMESPACE

@@ -1,5 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(roxygen2::roxy_tag_parse,roxy_tag_elfReusableExamples)
+S3method(roxygen2::roxy_tag_rd,roxy_tag_elfReusableExamples)
 export(assert_pkg_installed)
 export(assert_pkg_installed_but_not_via_loadall)
 export(check_pkg_installed)

R/examples.R

@@ -1,3 +1,5 @@
+# example path helper ====
+
 #' Source path_ex_files
 #'
 #' To use this in your package, re-declare `source_pef()` in your package
@@ -50,3 +52,60 @@ use_ex_file <- function(..., open = rlang::is_interactive()) {
 }
 
 example_path <- fs::path("inst", "examples")
+
+# elfReusableExamples tag ====
+
+#' Tag for reusable example code
+#'
+#' Provides new roxygen2 tag to make the `@examples` code reusable.
+#'
+#' @details
+#' Using this tag, you can reuse the expression in `@examples`.
+#' For example,
+#' your `@examples` may be an invocation of the documented function.
+#' You may often use the same invocation to write unit tests for the function.
+#' This tag lets you reuse the example code.
+#'
+#' Alternatively, you can store this code in a separate file,
+#' include it in the documentation via `@example`,
+#' and call it in tests and elsewhere via [source_pef()].
+#'
+#' @family example helpers
+#' @family testing helpers
+#'
+#' @name elfReusableExamples
+NULL
+
+#' @rdname elfReusableExamples
+#' @details
+#' `@elfReusableExamples ${1:name} {2:# example code}`
+#' Example code to be reused.
+#'
+#' Wraps @examples.
+#' @usage
+#' #' @elfResuableExamples ${1:name} {2:# example code}
+#' @name tag_reusable_examples
+NULL
+
+#' @exportS3Method roxygen2::roxy_tag_parse
+roxy_tag_parse.roxy_tag_elfReusableExamples <- function(x) {
+  check_pkg_installed("roxygen2")
+  check_pkg_installed("stringr")
+  parsed <- stringr::str_split(
+    x$raw,
+    pattern = stringr::boundary("word"),
+    n = 2,
+    simplify = TRUE
+  )
+  x$val <- list(
+    name = parsed[1, 1],
+    code = parsed[1, 2]
+  )
+  x
+}
+
+#' @exportS3Method roxygen2::roxy_tag_rd
+roxy_tag_rd.roxy_tag_elfReusableExamples <- function(x, base_path, env) {
+  res <- x[["val"]][["code"]]
+  roxygen2::rd_section("examples", res)
+}

inst/examples/elfReusableExamples/parse.R

@@ -0,0 +1,6 @@
+#' An example documentation of a resuable example
+#' @elfReusableExamples foo
+#' zap_fun(1, 2)
+#' @elfReusableExamples bar
+#' zap_fun(2, 3)
+zap_fun <- function(...) sum(...)

tests/testthat/_snaps/examples.md

@@ -0,0 +1,46 @@
+# roxy_tag_elfReusableExamples: can be parsed
+
+    Code
+      roxygen2::parse_text(example)[[1]]$tag
+    Output
+      [[1]]
+      [<text>:  1] @title 'An example documentation of a resuable example' {parsed}
+      
+      [[2]]
+      [<text>:  2] @elfReusableExamples 'foo...' {parsed}
+      
+      [[3]]
+      [<text>:  4] @elfReusableExamples 'bar...' {parsed}
+      
+      [[4]]
+      [<text>:  6] @usage '<generated>' {parsed}
+      
+      [[5]]
+      [<text>:  6] @.formals '<generated>' {parsed}
+      
+      [[6]]
+      [<text>:  6] @backref '<generated>' {parsed}
+      
+
+# roxy_tag_elfReusableExamples: can separate name and code
+
+    Code
+      roxygen2::parse_text(example)[[1]]$tag[[2]]$val
+    Output
+      $name
+      [1] "foo"
+      
+      $code
+      [1] "zap_fun(1, 2)"
+      
+
+# roxy_tag_elfReusableExamples: can be formatted
+
+    Code
+      topic$get_section("examples")
+    Output
+      \examples{
+      zap_fun(1, 2)
+      zap_fun(2, 3)
+      } 
+

tests/testthat/test-examples.R

@@ -0,0 +1,23 @@
+describe("roxy_tag_elfReusableExamples", {
+  example <- brio::read_file(
+    fs::path_package(
+      package = "elf",
+      "examples", "elfReusableExamples", "parse", ext = "R"
+    )
+  )
+  it(
+    "can be parsed",
+    expect_snapshot(roxygen2::parse_text(example)[[1]]$tag)
+  )
+  it(
+    "can separate name and code",
+    expect_snapshot(roxygen2::parse_text(example)[[1]]$tag[[2]]$val)
+  )
+  it(
+    "can be formatted",
+    {
+      topic <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), example)[[1]]
+      expect_snapshot(topic$get_section("examples"))
+    }
+  )
+})