Merge pull request #563 from owenjonesuob/hook-parsable-roxygen

Add parsable-roxygen hook

Author: lorenzwalthert

.pre-commit-hooks.yaml

@@ -49,6 +49,13 @@
     language: r
     files: '\.[rR](md)?$'
     minimum_pre_commit_version: "2.13.0"
+-   id: parsable-roxygen
+    name: parsable-roxygen
+    description: check if roxygen comments in a .R file are parsable
+    entry: Rscript inst/hooks/exported/parsable-roxygen.R
+    language: r
+    files: '\.[rR]$'
+    minimum_pre_commit_version: "2.13.0"
 -   id: readme-rmd-rendered
     name: readme-rmd-rendered
     description: make sure README.Rmd hasn't been edited more recently than `README.md`

DESCRIPTION

@@ -47,7 +47,7 @@ Roxygen: list(markdown = TRUE, roclets = c( "rd", "namespace", "collate",
     if (rlang::is_installed("pkgapi")) "pkgapi::api_roclet" else {
     warning("Please install r-lib/pkgapi to make sure the file API is kept
     up to date"); NULL} ) )
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 SystemRequirements: git
 Config/testthat/parallel: true
 Config/testthat/edition: 3

inst/hooks/exported/parsable-roxygen.R

@@ -0,0 +1,44 @@
+#!/usr/bin/env Rscript
+
+"Check whether roxygen comments within files are valid
+Usage:
+  parsable-roxygen [--eval] <files>...
+
+Options:
+  --eval  Evaluate file contents after parsing - this is required if `@eval` tags must be evaluated
+
+" -> doc
+
+arguments <- precommit::precommit_docopt(doc)
+
+if (packageVersion("roxygen2") < package_version("7.3.0")) {
+  rlang::abort("You need at least version 7.3.0 of {roxygen2} to run this hook.")
+}
+
+out <- lapply(arguments$files, function(path) {
+  tryCatch(
+    # Capture any messages from roxygen2:::warn_roxy()
+    msg <- capture.output(
+      roxygen2::parse_file(
+        path,
+        env = if (isTRUE(arguments$eval)) {
+          roxygen2::env_file(path)
+        } else {
+          NULL
+        }
+      ),
+      type = "message"
+    ),
+
+    # In case we encounter a more general file parsing problem
+    error = function(e) {
+      cat(c("File ", path, " is not parsable. Full context:\n"))
+      stop(conditionMessage(e), call. = FALSE)
+    }
+  )
+
+  if (length(msg) > 0) {
+    cat(c("Roxygen commentary in file ", path, " is not parsable. Full context:\n"))
+    stop(paste0(msg, collapse = "\n"), call. = FALSE)
+  }
+})

inst/pre-commit-hooks.yaml

@@ -49,6 +49,13 @@
     language: r
     files: '\.[rR](md)?$'
     minimum_pre_commit_version: "2.13.0"
+-   id: parsable-roxygen
+    name: parsable-roxygen
+    description: check if roxygen comments in a .R file are parsable
+    entry: Rscript inst/hooks/exported/parsable-roxygen.R
+    language: r
+    files: '\.[rR]$'
+    minimum_pre_commit_version: "2.13.0"
 -   id: readme-rmd-rendered
     name: readme-rmd-rendered
     description: make sure README.Rmd hasn't been edited more recently than `README.md`

tests/testthat/in/parsable-roxygen-fail.R

@@ -0,0 +1,18 @@
+#' Some function
+#' 
+#' This function is great! But \code{oh dear, a missing brace...
+#' 
+#' And isn't that a multi-line example? We should probably use @examples...
+#' 
+#' @param x A parameter.
+#'
+#' @returns Invisible `NULL`.
+#' 
+#' @example
+#' some_function(10)
+#' some_function(11)
+#' 
+#' @export
+some_function <- function(x) {
+  x
+}

tests/testthat/in/parsable-roxygen-fail2.R

@@ -0,0 +1,6 @@
+#' Minimal roxygen docs, but there's a problem with our R code!
+#' 
+#' @export
+some_function <- function(x) {
+  (x
+}

tests/testthat/in/parsable-roxygen-success.R

@@ -0,0 +1,18 @@
+#' Some function
+#' 
+#' This function is great!
+#' 
+#' @param x A parameter.
+#'
+#' @returns Invisible `NULL`.
+#' 
+#' @examples
+#' some_function(10)
+#' 
+#' @export
+some_function <- function(x) {
+  x
+}
+
+# To check whether code was evaluated
+print("A random print statement")

tests/testthat/reference-objects/pre-commit-config.yaml

@@ -59,6 +59,7 @@ repos:
           )$
     -   id: readme-rmd-rendered
     -   id: parsable-R
+    -   id: parsable-roxygen
     -   id: no-browser-statement
     -   id: no-print-statement
     -   id: no-debug-statement

tests/testthat/test-hook-parsable-roxygen.R

@@ -0,0 +1,36 @@
+# success - code not evaluated
+run_test(
+  "parsable-roxygen",
+  suffix = "-success.R",
+  std_out = NULL,
+  std_err = NULL,
+  read_only = TRUE
+)
+
+# success - code evaluated
+run_test(
+  "parsable-roxygen",
+  suffix = "-success.R",
+  cmd_args = "--eval",
+  std_out = "A random print statement",
+  std_err = NULL,
+  read_only = TRUE
+)
+
+# failure - roxygen problem
+run_test(
+  "parsable-roxygen",
+  suffix = "-fail.R",
+  std_out = "Roxygen commentary",
+  std_err = "@description has mismatched braces or quotes",
+  read_only = TRUE
+)
+
+# failure - R problem
+run_test(
+  "parsable-roxygen",
+  suffix = "-fail2.R",
+  std_out = "File ",
+  std_err = "unexpected '}'",
+  read_only = TRUE
+)

vignettes/available-hooks.Rmd

@@ -139,6 +139,34 @@ returns an error.
 
 This hook does not modify files.
 
+## `parsable-roxygen`
+
+Checks if roxygen comments within your `.R` files are "valid" by checking if
+running `roxygen2::parse_file()` on them returns any messages.
+
+This hook does not modify files.
+
+**eval**
+
+By default, each file will be parsed, but code will not be evaluated - neither
+any explicit code in the file, nor any `@eval` tags within roxygen comments.
+
+If your commentary contains `@eval` tags which you would prefer to evaluate, you
+can specify the `--eval` flag, which will cause the file's code to be evaluated
+in an environment created by `roxygen2::env_file()`. Note that dependencies of
+the code to evaluate must be available for pre-commit. You may list these as
+`additional_dependencies:` for the `parsable-roxygen` hook in
+`.pre-commit-config.yaml`.
+
+Inline R code within roxygen comments (i.e. within backticks) is **not**
+evaluated by this hook, whether or not `--eval` is specified. You would need
+to run the `roxygenize` hook for that.
+
+      id: parsable-roxygen
+      args: [--eval]
+    
+This hook was added in version 0.4.3.9000.
+
 ## `no-browser-statement`
 
 Guarantees you that you don't accidentally commit code with a