Tweak roxygen2 workflow

NEWS.md

@@ -1,5 +1,11 @@
 # usethis (development version)
 
+* `create_package()` gains a `roxygen` argument. If `TRUE` (the default), 
+  adds a `RoxygenNote` field to the `DESCRIPTION` (which means the first run
+  of `devtools::check()` will re-document the package, #963), and creates an 
+  empty `NAMESPACE` (which means you'll always need an explicit `@export` 
+  if you want to export functions, #927).
+
 * `pr_pull()` gives more information about which files have merge conflicts 
   and automatically opens conflicted files for editing (#1056).
 

R/create.R

@@ -9,9 +9,10 @@
 #' Both functions can be called on an existing project; you will be asked
 #' before any existing files are changed.
 #'
+#' @inheritParams use_description
 #' @param path A path. If it exists, it is used. If it does not exist, it is
 #'   created, provided that the parent path exists.
-#' @inheritParams use_description
+#' @param roxygen Do you plan to use roxygen2 to document your package?
 #' @param rstudio If `TRUE`, calls [use_rstudio()] to make the new package or
 #'   project into an [RStudio
 #'   Project](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects).
@@ -30,6 +31,7 @@
 create_package <- function(path,
                            fields = NULL,
                            rstudio = rstudioapi::isAvailable(),
+                           roxygen = TRUE,
                            check_name = TRUE,
                            open = interactive()) {
   path <- user_path_prep(path)
@@ -46,8 +48,8 @@ create_package <- function(path,
   on.exit(proj_set(old_project), add = TRUE)
 
   use_directory("R")
-  use_description(fields, check_name = check_name)
-  use_namespace()
+  use_description(fields, check_name = check_name, roxygen = roxygen)
+  use_namespace(roxygen = roxygen)
 
   if (rstudio) {
     use_rstudio()

R/description.R

@@ -40,6 +40,7 @@
 #'   personalized defaults using package options
 #' @param check_name Whether to check if the name is valid for CRAN and throw an
 #'   error if not
+#' @param roxygen If `TRUE`, sets `RoxygenNote` to current roxygen2 version.
 #' @seealso The [description chapter](https://r-pkgs.org/description.html#dependencies)
 #'   of [R Packages](https://r-pkgs.org).
 #' @export
@@ -51,14 +52,17 @@
 #'
 #' use_description_defaults()
 #' }
-use_description <- function(fields = NULL, check_name = TRUE) {
+use_description <- function(fields = NULL, check_name = TRUE, roxygen = TRUE) {
   name <- project_name()
   if (check_name) {
     check_package_name(name)
   }
   fields <- fields %||% list()
   check_is_named_list(fields)
   fields[["Package"]] <- name
+  if (roxygen) {
+    fields[["RoxygenNote"]] <- utils::packageVersion("roxygen2")
+  }
 
   desc <- build_description(fields)
   desc <- desc::description$new(text = desc)

R/namespace.R

@@ -1,13 +1,21 @@
 #' Use a basic `NAMESPACE`
 #'
-#' This `NAMESPACE` exports everything, except functions that start
-#' with a `.`.
+#' If `roxygen` is `TRUE` generates an empty `NAMESPACE` that exports nothing;
+#' you'll need to explicitly export functions with `@export`. If `roxygen`
+#' is `FALSE`, generates a default `NAMESPACE` that exports all functions
+#' except those that start with `.`.
 #'
+#' @param roxygen Do you plan to manage `NAMESPACE` with roxygen2?
 #' @seealso The [namespace chapter](https://r-pkgs.org/namespace.html) of
 #'   [R Packages](https://r-pkgs.org).
-#'
 #' @export
-use_namespace <- function() {
+use_namespace <- function(roxygen = TRUE) {
   check_is_package("use_namespace()")
-  use_template("NAMESPACE")
+
+  path <- proj_path("NAMESPACE")
+  if (roxygen) {
+    write_over(path, c("# Generated by roxygen2: do not edit by hand", ""))
+  } else {
+    write_over(path, 'exportPattern("^[^\\.]")')
+  }
 }

tests/testthat/test-use-description.R → tests/testthat/test-description.R

@@ -1,5 +1,3 @@
-context("use_description")
-
 test_that("build_description_list() defaults to values built into usethis", {
   withr::local_options(list(usethis.description = NULL, devtools.desc = NULL))
   d <- build_description_list()

tests/testthat/test-use-roxygen.R

@@ -11,19 +11,3 @@ test_that("use_roxygen_md() adds DESCRIPTION fields to naive package", {
   expect_true(desc::desc_has_fields("RoxygenNote", pkg))
   expect_true(uses_roxygen_md())
 })
-
-test_that("use_roxygen_md() does not error on a roxygen-using package", {
-  skip_if_not_installed("roxygen2")
-  with_mock(
-    ## need to pass the check re: whether roxygen2md is installed
-    `usethis:::check_installed` = function(pkg) TRUE, {
-      scoped_temporary_package()
-      cat(
-        "RoxygenNote: 6.0.1\n",
-        file = proj_path("DESCRIPTION"),
-        append = TRUE
-      )
-      expect_error_free(use_roxygen_md())
-    }
-  )
-})

tests/testthat/test-use-tidy.R

@@ -16,8 +16,6 @@ test_that("use_tidy_eval() inserts the template file and Imports rlang", {
   skip_if_not_installed("roxygen2")
 
   pkg <- scoped_temporary_package()
-  ## fake the use of roxygen; this better in a test than use_roxygen_md()
-  use_description_field(name = "RoxygenNote", value = "6.0.1.9000")
   use_tidy_eval()
   expect_match(dir_ls(proj_path("R")), "utils-tidy-eval.R")
   expect_match(desc::desc_get("Imports", pkg), "rlang")