Polish code and docs re: options for DESCRIPTION fields

DESCRIPTION

@@ -30,8 +30,10 @@ Imports:
     gh,
     git2r (>= 0.21.0.9002),
     rematch2,
+    rlang,
     rprojroot,
     rstudioapi,
+    utils,
     whisker
 Suggests: 
     covr,
@@ -43,10 +45,10 @@ Suggests:
     styler,
     testthat (>= 2.0.0),
     withr
+Remotes: 
+    ropensci/git2r
 Encoding: UTF-8
+Language: en-US
 LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 6.0.1.9000
-Language: en-US
-Remotes: 
-    ropensci/git2r

NAMESPACE

@@ -35,6 +35,7 @@ export(use_data)
 export(use_data_raw)
 export(use_depsy_badge)
 export(use_description)
+export(use_description_defaults)
 export(use_dev_package)
 export(use_dev_version)
 export(use_directory)

NEWS.md

@@ -1,6 +1,9 @@
 # usethis 1.3.0.9000
 
-* `use_tibble()` does minimum setup necessary for a package that returns or exports a tibble. For example, this guarantees it will print as a tibble (#324 @martinjhnhadley).
+* The logic for setting DESCRIPTION fields in `create_package()` and `use_description()` has gotten a Spring Cleaning. Fields directly specified by the user take precedence, then the named list in `getOption("usethis.description")` is consulted, and finally defaults built into usethis. `use_description_defaults()` is a new function that reveals fields found in options and built into usethis. Options specific to one DESCRIPTION field, e.g. `devtools.desc.license`, are no longer supported. Instead, use a single named list for all fields, preferably stored in an option named `"usethis.description"` (however,`"devtools.desc"` is still consulted for backwards compatibility). (#159, #233, #367)
+
+* `use_tibble()` does minimum setup necessary for a package that returns or exports a tibble. For example, this guarantees a tibble will print as a tibble (#324 @martinjhnhadley).
+
 * `use_logo()` to resize and add a logo to a package (#358, @jimhester).
 
 * `use_depsy_badge()` is defunct. The Depsy project has officially concluded and is no longer being maintained (#354).

R/create.R

@@ -26,7 +26,7 @@
 #'   in RStudio, working directory is set to the new project.
 #' @export
 create_package <- function(path,
-                           fields = getOption("devtools.desc"),
+                           fields = NULL,
                            rstudio = rstudioapi::isAvailable(),
                            open = interactive()) {
   path <- normalizePath(path, mustWork = FALSE)
@@ -44,7 +44,7 @@ create_package <- function(path,
 
   use_directory("R")
   use_directory("man")
-  use_description(fields = fields)
+  use_description(fields)
   use_namespace()
 
   if (rstudio) {

R/description.R

@@ -1,74 +1,89 @@
-#' Create a default DESCRIPTION file for a package.
+#' Create a DESCRIPTION file
 #'
 #' @description
-#' If you create a lot of packages, you can override the defaults by setting
-#' option `"usethis.description"` to a named list. Here's an example of code one
-#' could include in `.Rprofile`:
+#' usethis consults the following sources, in this order, to set DESCRIPTION
+#' fields:
+#' * `fields` argument of [create_package()] or [use_description()]
+#' * `getOption("usethis.description")` or `getOption("devtools.desc")`. The
+#' devtools option is consulted only for backwards compatibility and it's
+#' recommended to switch to an option named "usethis.description".
+#' * Defaults built into usethis
+#'
+#' The fields discovered via options or the usethis package can be viewed with
+#' `use_description_defaults()`.
+#'
+#' If you create a lot of packages, consider storing personalized defaults as a
+#' named list in an option named `"usethis.description"`. Here's an example of
+#' code to include in `.Rprofile`:
 #'
 #' ```
 #' options(
-#'   usethis.name = "Jane Doe",
 #'   usethis.description = list(
-#'     `Authors@R` = 'person("Jane", "Doe", email = "jane@example.com", role = c#' ("aut", "cre"))',
+#'     `Authors@R` = 'person("Jane", "Doe", email = "jane@example.com", role = c("aut", "cre"))',
 #'     License = "MIT + file LICENSE",
-#'     Version = "0.0.0.9000"
+#'     Language: es
 #'   )
 #' )
 #' ```
 #'
-#' @param fields A named list of fields to add to \file{DESCRIPTION},
-#'   potentially overriding the defaults. If `NULL`, retrieved from
-#'   `getOption("usethis.description")`, and (for backward compatibility) from
-#'   `getOption("devtools.desc")`.
+#' @param fields A named list of fields to add to DESCRIPTION, potentially
+#'   overriding default values. See [use_description()] for how you can set
+#'   personalized defaults using package options
 #' @export
 #' @examples
 #' \dontrun{
 #' use_description()
+#'
+#' use_description(fields = list(Language = "es"))
+#'
+#' use_description_defaults()
 #' }
 use_description <- function(fields = NULL) {
   name <- project_name()
   check_package_name(name)
+  fields <- fields %||% list()
+  check_is_named_list(fields)
+  fields[["Package"]] <- name
 
-  fields <- fields %||%
-    getOption("usethis.description") %||%
-    getOption("devtools.desc") %||%
-    list()
-
-  desc <- build_description(name, fields)
+  desc <- build_description(fields)
   write_over(proj_get(), "DESCRIPTION", desc)
 }
 
-build_description <- function(name, fields = list()) {
-  desc_list <- build_description_list(name, fields)
+#' @rdname use_description
+#' @export
+use_description_defaults <- function() {
+  list(
+    usethis.description = getOption("usethis.description"),
+    devtools.desc = getOption("devtools.desc"),
+    usethis = list(
+      Package = "valid.package.name.goes.here",
+      Version = "0.0.0.9000",
+      Title = "What the Package Does (One Line, Title Case)",
+      Description = "What the package does (one paragraph).",
+      "Authors@R" = 'person("First", "Last", , "first.last@example.com", c("aut", "cre"))',
+      License = "What license it uses",
+      Encoding = "UTF-8",
+      LazyData = "true"
+    )
+  )
+}
+
+build_description <- function(fields = list()) {
+  desc_list <- build_description_list(fields)
 
   # Collapse all vector arguments to single strings
   desc <- vapply(desc_list, function(x) paste(x, collapse = ", "), character(1))
 
   paste0(names(desc), ": ", desc)
 }
 
-build_description_list <- function(name, fields = list()) {
-  author <- getOption("devtools.desc.author") %||%
-    'person("First", "Last", , "first.last@example.com", c("aut", "cre"))'
-  license <- getOption("devtools.desc.license") %||% "What license it uses"
-  suggests <- getOption("devtools.desc.suggests")
-
-  defaults <- list(
-    Package = name,
-    Version = "0.0.0.9000",
-    Title = "What the Package Does (One Line, Title Case)",
-    Description = "What the package does (one paragraph).",
-    "Authors@R" = author,
-    License = license,
-    Suggests = suggests,
-    Encoding = "UTF-8",
-    LazyData = "true",
-    ByteCompile = "true"
+build_description_list <- function(fields = list()) {
+  defaults <- use_description_defaults()
+  defaults <- utils::modifyList(
+    defaults$usethis,
+    defaults$usethis.description %||% defaults$devtools.desc %||% list()
   )
-
-  # Override defaults with user supplied options
-  desc <- utils::modifyList(defaults, fields)
-  compact(desc)
+  compact(utils::modifyList(defaults, fields))
 }
 
 check_package_name <- function(name) {

R/license.R

@@ -96,13 +96,13 @@ license_data <- function(name, base_path = proj_get()) {
 
 
 find_name <- function() {
-  name <- getOption("devtools.name")
-  if (!is.null(name) && name != "Your name goes here") {
+  name <- getOption("usethis.full_name")
+  if (!is.null(name)) {
     return(name)
   }
 
-  name <- getOption("usethis.full_name")
-  if (!is.null(name)) {
+  name <- getOption("devtools.name")
+  if (!is.null(name) && name != "Your name goes here") {
     return(name)
   }
 

R/utils.R

@@ -62,6 +62,20 @@ check_is_empty <- function(x) {
   invisible(x)
 }
 
+check_is_named_list <- function(x, nm = deparse(substitute(x))) {
+  if (!rlang::is_list(x)) {
+    bad_class <- paste(class(x), collapse = "/")
+    stop(code(nm), " must be a list, not ", bad_class, call. = FALSE)
+  }
+  if (!rlang::is_dictionaryish(x)) {
+    stop(
+      "Names of ", code(nm), " must be non-missing, non-empty, and ",
+      "non-duplicated.", call. = FALSE
+    )
+  }
+  x
+}
+
 dots <- function(...) {
   eval(substitute(alist(...)))
 }