updated vignettes

Author: pachadotdev

.Rbuildignore

@@ -31,6 +31,7 @@ script.R
 ^\.cache$
 ^docs$
 ^pkgdown$
+^cpp4rexamples$
 ^cpp4rdummyols$
 ^cpp4rgaussjordan$
 ^cpp4romp$

.github/workflows/R-CMD-check.yaml

@@ -50,7 +50,7 @@ jobs:
       - uses: pachadotdev/clang-format@main
         if: matrix.config.custom == 'clang-format'
         with:
-          version: '14'
+          version: '18'
           files: 'src/*.cpp src/*.h inst/include/*.h'
           auto-commit: true
           commit-message: 'style: format C++ code in R package'

Makefile

@@ -20,7 +20,7 @@ site:
 install:
 	@Rscript -e 'devtools::install()'
 
-clang_format=`which clang-format-20`
+clang_format=`which clang-format-18`
 
 format: $(shell find . -name '*.h') $(shell find . -name '*.hpp') $(shell find . -name '*.cpp')
 	@${clang_format} -i $?

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(pkg_template)
 export(register)
 export(unvendor)
 export(vendor)

R/register.R

@@ -77,17 +77,16 @@ register <- function(path = ".", quiet = !is_interactive(), extension = c(".cpp"
     cli::cli_alert_success("generated file {.file {basename(r_path)}}")
   }
 
-
   call_entries <- get_call_entries(path, funs$name, package)
 
   cpp_function_registration <- glue::glue_data(funs, '    {{
     "_cpp4r_{name}", (DL_FUNC) &_{package}_{name}, {n_args}}}, ',
     n_args = viapply(funs$args, nrow)
   )
 
-  cpp_function_registration <- glue::glue_collapse(cpp_function_registration, sep  = "\n")
+  cpp_function_registration <- glue::glue_collapse(cpp_function_registration, sep = "\n")
 
-  extra_includes <-  character()
+  extra_includes <- character()
   if (pkg_links_to_rcpp(path)) {
     extra_includes <- c(extra_includes, "#include <cpp4r/R.hpp>", "#include <Rcpp.h>", "using namespace Rcpp;")
   }
@@ -215,35 +214,92 @@ generate_init_functions <- function(funs) {
 }
 
 generate_r_functions <- function(funs, package = "cpp4r", use_package = FALSE) {
-  funs <- funs[c("name", "return_type", "args")]
+  funs <- funs[c("name", "return_type", "args", "file", "line", "decoration")]
 
   if (use_package) {
     package_call <- glue::glue(', PACKAGE = "{package}"')
     package_names <- glue::glue_data(funs, '"_{package}_{name}"')
   } else {
-    package_names <- glue::glue_data(funs, '`_{package}_{name}`')
+    package_names <- glue::glue_data(funs, "`_{package}_{name}`")
     package_call <- ""
   }
 
-  funs$package <- package
   funs$package_call <- package_call
   funs$list_params <- vcapply(funs$args, glue_collapse_data, "{name}")
   funs$params <- vcapply(funs$list_params, function(x) if (nzchar(x)) paste0(", ", x) else x)
   is_void <- funs$return_type == "void"
   funs$calls <- ifelse(is_void,
-    glue::glue_data(funs, 'invisible(.Call({package_names}{params}{package_call}))'),
-    glue::glue_data(funs, '.Call({package_names}{params}{package_call})')
+    glue::glue_data(funs, "invisible(.Call({package_names}{params}{package_call}))"),
+    glue::glue_data(funs, ".Call({package_names}{params}{package_call})")
   )
 
-  out <- glue::glue_data(funs, '
-    {name} <- function({list_params}) {{
-      {calls}
-    }}
-    ')
+  # Parse and associate Roxygen comments
+  funs$roxygen_comment <- mapply(function(file, line) {
+    if (file.exists(file)) {
+      comments <- extract_roxygen_comments(file)
+      matched_comment <- ""
+      for (comment in comments) {
+        # Check if the comment directly precedes the function without gaps
+        if (line == comment$line + 1) {
+          matched_comment <- comment$text
+          break
+        }
+      }
+      matched_comment
+    } else {
+      ""
+    }
+  }, funs$file, funs$line, SIMPLIFY = TRUE)
+
+  # Generate R functions with or without Roxygen comments
+  out <- mapply(function(name, list_params, calls, roxygen_comment) {
+    if (nzchar(roxygen_comment)) {
+      glue::glue("{roxygen_comment}\n{name} <- function({list_params}) {{\n\t{calls}\n}}")
+    } else {
+      glue::glue("{name} <- function({list_params}) {{\n  {calls}\n}}")
+    }
+  }, funs$name, funs$list_params, funs$calls, funs$roxygen_comment, SIMPLIFY = TRUE)
+
+  out <- glue::trim(out)
   out <- glue::glue_collapse(out, sep = "\n\n")
   unclass(out)
 }
 
+extract_roxygen_comments <- function(file) {
+  lines <- readLines(file)
+  
+  # Look for roxygen comments that start with /* roxygen
+  roxygen_start <- grep("^/\\* roxygen\\s*$", lines)
+  
+  if (length(roxygen_start) == 0) {
+    return(list())
+  }
+  
+  roxygen_comments <- lapply(roxygen_start, function(start) {
+    # Find the end of the comment block (line ending with */)
+    end_line <- start + 1
+    while (end_line <= length(lines) && !grepl("\\*/$", lines[end_line])) {
+      end_line <- end_line + 1
+    }
+    
+    # If we didn't find an end, skip this comment
+    if (end_line > length(lines)) {
+      return(NULL)
+    }
+    
+    # Extract the roxygen content (excluding the start and end lines)
+    roxygen_lines <- lines[(start + 1):(end_line - 1)]
+    
+    # Convert to R roxygen format by adding #' prefix
+    roxygen_lines <- sub("^", "#' ", roxygen_lines)
+    
+    list(line = end_line, text = paste(roxygen_lines, collapse = "\n"))
+  })
+  
+  # Remove NULL entries
+  roxygen_comments[!sapply(roxygen_comments, is.null)]
+}
+
 wrap_call <- function(name, return_type, args) {
   call <- glue::glue('{name}({list_params})', list_params = glue_collapse_data(args, "cpp4r::as_cpp<cpp4r::decay_t<{type}>>({name})"))
   if (return_type == "void") {

R/template.R

@@ -0,0 +1,97 @@
+# The function itself just echos its inputs and outputs to a file called INDEX,
+# which is then opened by RStudio when the new project is opened.
+#' Start a new project with the cpp4r package template
+#' @param path Path to the new project
+#' @param pkgname Name of the new package
+#' @return The file path to the copied template (invisibly).
+#' @examples
+#' # create a new directory
+#' dir <- tempdir()
+#' dir.create(dir)
+#'
+#' # copy the package template into the directory
+#' pkg_template(dir, "mynewpkg")
+#' @export
+pkg_template <- function(path = NULL, pkgname = NULL) {
+  if (is.null(path)) {
+    stop("You must provide a path to the new project", call. = FALSE)
+  }
+  if (is.null(pkgname)) {
+    pkgname <- basename(path)
+  }
+
+  # ensure path exists
+  dir.create(path, recursive = TRUE, showWarnings = FALSE)
+
+  # copy files
+  file.copy(
+    list.files(
+      system.file("extdata/pkgtemplate", "", package = "cpp4r"),
+      full.names = TRUE
+    ),
+    path,
+    recursive = TRUE
+  )
+
+  dir.create(paste0(path, "/R"), recursive = TRUE, showWarnings = FALSE)
+
+  lines <- c(
+    "^.*\\.Rproj$",
+    "^\\.Rproj\\.user$",
+    "^\\.Renviron$",
+    "^docs$",
+    "^vignettes/images$",
+    "^\\.github$",
+    "^\\.vscode$",
+    "^dev$",
+    "^LICENSE\\.md$",
+    "^README$",
+    "^README\\.Rmd$"
+  )
+
+  writeLines(lines, con = paste0(path, "/.Rbuildignore"))
+
+  lines <- c(
+    paste0("#' @useDynLib ", pkgname, ", .registration = TRUE"),
+    "#' @keywords internal",
+    "\"_PACKAGE\""
+  )
+
+  writeLines(lines, con = paste0(path, "/R/", pkgname, "-package.R"))
+
+  # get roxygen version
+  roxyver <- as.character(utils::packageVersion("roxygen2"))
+
+  lines <- c(
+    paste("Package:", pkgname),
+    "Type: Package",
+    "Title: ADD TITLE",
+    "Version: 0.1",
+    "Authors@R: c(",
+    "    person(",
+    "        given = \"YOUR\",",
+    "        family = \"NAME\",",
+    "        role = c(\"aut\", \"cre\"),",
+    "        email = \"[email protected]\",",
+    "        comment = c(ORCID = \"0000-0001-0002-0003\"))",
+    "    )",
+    "Suggests: ",
+    "    knitr,",
+    "    rmarkdown",
+    "Depends: R(>= 3.5.0)",
+    "Description: ADD DESCRIPTION. TWO OR MORE LINES",
+    "License: ADD LICENSE",
+    "BugReports: https://github.com/USERNAME/PKGNAME/issues",
+    "URL: https://WEBSITE.COM",
+    # "RoxygenNote: 7.3.0",
+    paste0("RoxygenNote: ", roxyver),
+    "Encoding: UTF-8",
+    "NeedsCompilation: yes",
+    "VignetteBuilder: knitr",
+    "LinkingTo: cpp4r"
+  )
+
+  writeLines(lines, con = paste0(path, "/DESCRIPTION"))
+
+  invisible(path)
+}

README.md

@@ -24,24 +24,37 @@ After discussing some [pull requests](https://github.com/r-lib/cpp11/pulls/pacha
 - [x] Provide flexibility with data types (e.g., cpp4r's `as_integers()` and `as_doubles()` accept logical inputs while cpp11's do not).
 - [x] Some internal optimizations for better speed (e.g., https://github.com/r-lib/cpp11/pull/463 and https://github.com/r-lib/cpp11/pull/430).
 
+## Getting started
+
+Check the [documentation](https://cpp4r.org/) to get started using cpp4r in your scripts, particularly if you are new to C++ programming.
+
 ## Using cpp4r in a package
 
+Create a new package with `cpp4r::pkg_template("~/path/to/mypkg")` and then edit the generated files.
+
 To add cpp4r to an existing package, put your C++ files in the `src/` directory and add the following to your DESCRIPTION file:
 
 ```
 LinkingTo: cpp4r
 ```
 
+Then add a roxygen header, for example, to `R/mypkg-package.R`:
+
+```r
+#' @useDynLib mypkg, .registration = TRUE
+#' @keywords internal
+"_PACKAGE"
+```
+
 Then decorate C++ functions you want to expose to R with `[[cpp4r::register]]`.
 
-cpp4r is a header only library with no hard dependencies and does not use a shared library, so it is straightforward and reliable to use in packages without fear of compile-time and run-time mismatches.
+cpp4r is a header only library with no hard dependencies and does not use a shared library. It is straightforward and reliable to use in packages without fear of compile-time and run-time mismatches.
 
-Alternatively, you can [vendor](https://cpp4r.org/articles/motivations.html#vendoring) the current installed version of cpp4r headers into your package with `cpp4r::vendor_cpp4r()`.
-This ensures the headers will remain unchanged until you explicitly update them.
+## Vendoring
 
-## Getting started
+You can [vendor](https://cpp4r.org/articles/motivations.html#vendoring) the current installed version of cpp4r headers into your package with `cpp4r::vendor_cpp4r()`.
 
-See [vignette("cpp4r")](https://cpp4r.org/articles/cpp4r.html) to get started using cpp4r in your scripts, particularly if you are new to C++ programming.
+This ensures the headers will remain unchanged until you explicitly update them.
 
 ## Getting help
 

_pkgdown.yml

@@ -1,5 +1,5 @@
 template:
   bootstrap: 5
 
-url: https://cpp4r.org
+url: "./"
 destination: docs

cpp4rexamples/.Rbuildignore

@@ -0,0 +1,11 @@
+^.*\.Rproj$
+^\.Rproj\.user$
+^\.Renviron$
+^docs$
+^vignettes/images$
+^\.github$
+^\.vscode$
+^dev$
+^LICENSE\.md$
+^README$
+^README\.Rmd$

cpp4rexamples/DESCRIPTION

@@ -0,0 +1,25 @@
+Package: cpp4rexamples
+Type: Package
+Title: ADD TITLE
+Version: 0.1
+Authors@R: c(
+    person(
+        given = "YOUR",
+        family = "NAME",
+        role = c("aut", "cre"),
+        email = "[email protected]",
+        comment = c(ORCID = "0000-0001-0002-0003"))
+    )
+Suggests: 
+    knitr,
+    rmarkdown
+Depends: R(>= 3.5.0)
+Description: ADD DESCRIPTION. TWO OR MORE LINES
+License: ADD LICENSE
+BugReports: https://github.com/USERNAME/PKGNAME/issues
+URL: https://WEBSITE.COM
+RoxygenNote: 7.3.2
+Encoding: UTF-8
+NeedsCompilation: yes
+VignetteBuilder: knitr
+LinkingTo: cpp4r