Merge branch 'main' into test-file-snapshot

Author: jennybc

DESCRIPTION

@@ -47,14 +47,9 @@ Suggests:
     DT (>= 0.23),
     foghorn (>= 1.4.2),
     gh (>= 1.3.0),
-    gmailr (>= 1.0.1),
     httr (>= 1.4.3),
     knitr (>= 1.39),
     lintr (>= 3.0.0),
-    MASS,
-    mockery (>= 0.4.3),
-    pingr (>= 2.0.1),
-    rhub (>= 1.1.1),
     rmarkdown (>= 2.14),
     rstudioapi (>= 0.13),
     spelling (>= 2.2)

NAMESPACE

@@ -13,6 +13,7 @@ export(build_vignettes)
 export(check)
 export(check_built)
 export(check_dep_version)
+export(check_doc_fields)
 export(check_mac_devel)
 export(check_mac_release)
 export(check_man)
@@ -82,8 +83,6 @@ export(uses_testthat)
 export(wd)
 export(with_debug)
 import(fs)
-importFrom(cli,cat_bullet)
-importFrom(cli,cat_rule)
 importFrom(ellipsis,check_dots_used)
 importFrom(lifecycle,deprecated)
 importFrom(memoise,memoise)
@@ -105,11 +104,3 @@ importFrom(usethis,ui_path)
 importFrom(usethis,ui_todo)
 importFrom(usethis,ui_value)
 importFrom(usethis,use_test)
-importFrom(utils,available.packages)
-importFrom(utils,contrib.url)
-importFrom(utils,install.packages)
-importFrom(utils,installed.packages)
-importFrom(utils,modifyList)
-importFrom(utils,packageDescription)
-importFrom(utils,packageVersion)
-importFrom(utils,remove.packages)

NEWS.md

@@ -1,6 +1,8 @@
 # devtools (development version)
 
+* `bash()`, `create()`, `missing_s3()`, `reload()`, `show_news()`, and `wd()` are now deprecated. These functions are all historical parts of our workflow that we no longer use or recommend. `create()` is superseded by `usethis::create_package()`.
 * `build_manual()` reports more details on failure (#2586).
+* `check_doc_fields()` is a new function that checks for missing `\value` and `\examples` fields in Rd files, which are commonly flagged by CRAN (#2525).
 * `build_vignettes()` and `clean_vignettes()` are now deprecated. We no longer recommend building vignettes in this way; instead use `pkgdown::build_article()` to render articles locally (#2488).
 * `build_site()` now just calls `pkgdown::build_site()`, meaning that you will get more (informative) output by default (#2578).
 * New `check_mac_devel()` function to check a package using the macOS builder at https://mac.r-project.org/macbuilder/submit.html (@nfrerebeau, #2507)
@@ -11,6 +13,8 @@
 * `release()` is deprecated in favour of `usethis::use_release_issue()`.
 * `show_news()` now looks for NEWS files in the same locations as `utils::news()`: `inst/NEWS.Rd`, `NEWS.md`, `NEWS`, and `inst/NEWS` (@arcresu, #2499).
 * `test_active_file()` now works when the active file is a snapshot file.
+* `test_coverage()` and `test_coverage_active_file()` gain a new `report` argument that can be set to `"html"` (the default, for an interactive browser report), `"zero"` (prints uncovered lines to the console, used for LLMs and non-interactive contexts), or `"silent"`. The `show_report` argument has been removed (#2632).
+* `test_file()` and `test_coverage_file()` are now defunct. These were deprecated in devtools 2.4.0 (2021-04-07) in favour of `test_active_file()` and `test_coverage_active_file()`. Removing `test_file()` eliminates the conflict with `testthat::test_file()`.
 
 # devtools 2.4.6
 

R/bash.R

@@ -1,8 +1,16 @@
 #' Open bash shell in package directory
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `bash()` is deprecated because we no longer use or recommend this workflow.
+#' Open bash shell in package directory
+#'
 #' @template devtools
 #' @export
+#' @keywords internal
 bash <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "bash()")
   pkg <- as.package(pkg)
 
   withr::with_dir(pkg$path, system("bash"))

R/check-devtools.R

@@ -8,15 +8,15 @@
 #' @export
 release_checks <- function(pkg = ".", built_path = NULL) {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running additional devtools checks for ", pkg$package))
+  cli::cat_rule(paste0("Running additional devtools checks for ", pkg$package))
 
   check_version(pkg)
   check_dev_versions(pkg)
   check_vignette_titles(pkg)
   check_news_md(pkg)
   check_remotes(pkg)
 
-  cat_rule()
+  cli::cat_rule()
 }
 
 check_dev_versions <- function(pkg = ".") {

R/check-doc.R

@@ -62,3 +62,54 @@ man_message <- function(x) {
     FALSE
   }
 }
+
+#' Check for missing documentation fields
+#'
+#' Checks all Rd files in `man/` and looks for any that have a `\usage` section
+#' (i.e. a function) but that *don't* have `\value` and `\examples` sections.
+#' These missing fields are flagged by CRAN on initial submission.
+#'
+#' @template devtools
+#' @param fields A character vector of Rd field names to check for.
+#' @returns A named list of character vectors, one for each field, containing
+#'   the names of Rd files missing that field. Returned invisibly.
+#' @export
+#' @examples
+#' \dontrun{
+#' check_doc_fields(".")
+#' }
+check_doc_fields <- function(pkg = ".", fields = c("value", "examples")) {
+  pkg <- as.package(pkg)
+  fields <- stats::setNames(fields, fields)
+
+  paths <- dir_ls(path(pkg$path, "man"), regexp = "\\.Rd$")
+  names(paths) <- path_rel(paths, pkg$path)
+  rd <- lapply(paths, tools::parse_Rd, permissive = TRUE)
+  rd_tags <- lapply(rd, \(x) unlist(lapply(x, attr, "Rd_tag")))
+
+  has_tag <- function(tags, this) {
+    any(paste0("\\", this) %in% tags)
+  }
+
+  has_usage <- vapply(rd_tags, has_tag, logical(1), this = "usage")
+  rd_tags <- rd_tags[has_usage]
+
+  results <- lapply(fields, function(field) {
+    missing <- !vapply(rd_tags, has_tag, logical(1), this = field)
+    names(rd_tags)[missing]
+  })
+
+  for (field in fields) {
+    missing <- results[[field]]
+    if (length(missing) > 0) {
+      cli::cli_inform(c(
+        "!" = "Missing {.code \\{field}} section in {length(missing)} file{?s}:",
+        stats::setNames(missing, rep("*", length(missing)))
+      ))
+    } else {
+      cli::cli_inform(c("v" = "All Rd files have a {.code \\{field}} section."))
+    }
+  }
+
+  invisible(results)
+}

R/check-git.R

@@ -7,11 +7,11 @@
 #' @keywords internal
 git_checks <- function(pkg = ".") {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running Git checks for ", pkg$package))
+  cli::cat_rule(paste0("Running Git checks for ", pkg$package))
 
   git_report_branch(pkg)
   git_check_uncommitted(pkg)
-  cat_rule()
+  cli::cat_rule()
 }
 
 git_report_branch <- function(pkg) {

R/check.R

@@ -85,7 +85,7 @@ check <- function(
   document <- document %||% can_document(pkg$roxygennote)
   if (document) {
     if (!quiet) {
-      cat_rule("Documenting", col = "cyan", line = 2)
+      cli::cat_rule("Documenting", col = "cyan", line = 2)
     }
     document(pkg, quiet = quiet)
     if (!quiet) {
@@ -94,7 +94,7 @@ check <- function(
   }
 
   if (!quiet) {
-    cat_rule("Building", col = "cyan", line = 2)
+    cli::cat_rule("Building", col = "cyan", line = 2)
     show_env_vars(pkgbuild::compiler_flags(FALSE))
   }
 
@@ -133,7 +133,7 @@ check <- function(
   )
 }
 
-can_document <- function(required, installed = packageVersion("roxygen2")) {
+can_document <- function(required, installed = utils::packageVersion("roxygen2")) {
   if (is.null(required)) {
     return(FALSE)
   }
@@ -222,7 +222,7 @@ check_built <- function(
 
   env_vars <- check_env_vars(cran, remote, incoming, force_suggests, env_vars)
   if (!quiet) {
-    cat_rule("Checking", col = "cyan", line = 2)
+    cli::cat_rule("Checking", col = "cyan", line = 2)
     show_env_vars(env_vars)
   }
 
@@ -271,7 +271,7 @@ aspell_env_var <- function() {
 
 show_env_vars <- function(env_vars) {
   cli::cat_line("Setting env vars:", col = "darkgrey")
-  cat_bullet(
+  cli::cat_bullet(
     paste0(format(names(env_vars)), ": ", unname(env_vars)),
     col = "darkgrey"
   )

R/create.R

@@ -1,11 +1,19 @@
 #' Create a package
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `create()` is deprecated. Please use [usethis::create_package()] directly
+#' instead.
+#'
 #' @param path A path. If it exists, it is used. If it does not exist, it is
 #'   created, provided that the parent path exists.
 #' @param ... Additional arguments passed to [usethis::create_package()]
 #' @inheritParams usethis::create_package
 #' @return The path to the created package, invisibly.
 #' @export
+#' @keywords internal
 create <- function(path, ..., open = FALSE) {
+  lifecycle::deprecate_warn("2.5.0", "create()", "usethis::create_package()")
   usethis::create_package(path, ..., open = open)
 }

R/missing-s3.R

@@ -1,10 +1,17 @@
 #' Find missing s3 exports
 #'
-#' The method is heuristic - looking for objs with a period in their name.
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `missing_s3()` is deprecated because roxygen2 now provides the same
+#' functionality. Run `devtools::document()` and look for
+#' `"Missing documentation for S3 method"` warnings.
 #'
 #' @template devtools
 #' @export
+#' @keywords internal
 missing_s3 <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "missing_s3()")
   pkg <- as.package(pkg)
   loaded <- load_all(pkg$path)