From faaa646e446471424d31dbe0db7a5251af5412e0 Mon Sep 17 00:00:00 2001
From: Marco Colombo <mar.colombo13@gmail.com>
Date: Fri, 9 Jan 2026 18:22:05 +0100
Subject: [PATCH 1/2] Suggest a fix if a mismatch in roxygen2 versions is found
 during check.

---
 R/check.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/check.R b/R/check.R
index 11489ffb1..fb43b7c20 100644
--- a/R/check.R
+++ b/R/check.R
@@ -143,7 +143,7 @@ can_document <- function(pkg) {
     cli::cat_rule("Documenting", col = "red", line = 2)
     cli::cli_inform(c(
       i = "Installed roxygen2 version ({installed}) doesn't match required ({required})",
-      x = "{.fun check} will not re-document this package"
+      x = "{.fun check} will not re-document this package, use {.fun document} to update the {.file DESCRIPTION} file"
     ))
     FALSE
   } else {

From eb654bc58371524a6d3433f174a5754255a28caf Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Wed, 21 Jan 2026 10:49:06 -0600
Subject: [PATCH 2/2] Tweak error; refactor; improve test

---
 R/check.R                      | 12 +++++-------
 tests/testthat/_snaps/check.md | 11 +++++++++++
 tests/testthat/test-check.R    | 13 ++++---------
 3 files changed, 20 insertions(+), 16 deletions(-)
 create mode 100644 tests/testthat/_snaps/check.md

diff --git a/R/check.R b/R/check.R
index d01780f5a..e1617759e 100644
--- a/R/check.R
+++ b/R/check.R
@@ -82,7 +82,7 @@ check <- function(
   }
   error_on <- match.arg(error_on)
 
-  document <- document %||% can_document(pkg)
+  document <- document %||% can_document(pkg$roxygennote)
   if (document) {
     if (!quiet) {
       cat_rule("Documenting", col = "cyan", line = 2)
@@ -133,19 +133,17 @@ check <- function(
   )
 }
 
-can_document <- function(pkg) {
-  required <- pkg$roxygennote
+can_document <- function(required, installed = packageVersion("roxygen2")) {
   if (is.null(required)) {
-    # Doesn't use roxygen2 at all
     return(FALSE)
   }
 
-  installed <- packageVersion("roxygen2")
   if (required != installed) {
     cli::cat_rule("Documenting", col = "red", line = 2)
     cli::cli_inform(c(
-      i = "Installed roxygen2 version ({installed}) doesn't match required ({required})",
-      x = "{.fun check} will not re-document this package, use {.fun document} to update the {.file DESCRIPTION} file"
+      i = "Installed roxygen2 version ({installed}) doesn't match declared ({required})",
+      x = "{.fun check} will not re-document this package.",
+      i = "Do you need to re-run {.fun document}?"
     ))
     FALSE
   } else {
diff --git a/tests/testthat/_snaps/check.md b/tests/testthat/_snaps/check.md
new file mode 100644
index 000000000..fd15773dd
--- /dev/null
+++ b/tests/testthat/_snaps/check.md
@@ -0,0 +1,11 @@
+# can determine when to document
+
+    Code
+      result <- can_document("1.0.0", installed = "2.0.0")
+    Output
+      == Documenting =================================================================
+    Message
+      i Installed roxygen2 version (2.0.0) doesn't match declared (1.0.0)
+      x `check()` will not re-document this package.
+      i Do you need to re-run `document()`?
+
diff --git a/tests/testthat/test-check.R b/tests/testthat/test-check.R
index b9542a440..d5e9b23ec 100644
--- a/tests/testthat/test-check.R
+++ b/tests/testthat/test-check.R
@@ -1,13 +1,8 @@
 test_that("can determine when to document", {
-  expect_false(can_document(list()))
-  # TODO: switch to expect_snapshot()
-  expect_output(
-    expect_message(
-      expect_false(can_document(list(roxygennote = "15.0.00"))),
-      "doesn't match required"
-    )
-  )
-  expect_true(can_document(list(roxygennote = packageVersion("roxygen2"))))
+  expect_false(can_document(NULL))
+  expect_true(can_document("1.0.0", installed = "1.0.0"))
+  expect_snapshot(result <- can_document("1.0.0", installed = "2.0.0"))
+  expect_false(result)
 })
 
 test_that("fail instead of sending an email to wrong recipient", {