Make @docType package work more like _PACKAGE (#1535)

While recommending that you update to the newer syntax.

Fixes #1491

NEWS.md

@@ -1,5 +1,9 @@
 # roxygen2 (development version)
 
+* `@docType package` now works more like documenting `"_PACKAGE"`, 
+  creating a `{packagename}-package` alias and clearly suggesting that
+  you should switch to `"_PACKAGE"` instead (#1491).
+
 * `URL` and `BugReports` fields in `DESCRIPTION` may now contain 
   percent-encoded URLs (@HenningLorenzen-ext-bayer, #1415).
 

R/object-from-call.R

@@ -1,7 +1,7 @@
 object_from_call <- function(call, env, block, file) {
   if (is.character(call)) {
     if (identical(call, "_PACKAGE")) {
-      parser_package(call, env, block, file)
+      parser_package(file)
     } else {
       parser_data(call, env, file)
     }
@@ -36,6 +36,18 @@ object_from_call <- function(call, env, block, file) {
       NULL
     )
   } else {
+    # Patch @docType package to ensure that it gets a default alias
+    # and other "_PACKAGE" features
+    if (block_has_tags(block, "docType")) {
+      docType <- block_get_tag_value(block, "docType")
+      if (docType == "package") {
+        warn_roxy_block(block, c(
+          '`@docType "package"` is deprecated',
+          i = 'Please document "_PACKAGE" instead.'
+        ))
+        return(parser_package(file))
+      }
+    }
     NULL
   }
 }
@@ -85,14 +97,14 @@ parser_data <- function(call, env, block) {
   object(value, call, type = "data")
 }
 
-parser_package <- function(call, env, block, file) {
+parser_package <- function(file) {
 
   pkg_path <- dirname(dirname(file))
   value <- list(
     desc = desc::desc(file = pkg_path),
     path = pkg_path
   )
-  object(value, call, type = "package")
+  object(value, "_PACKAGE", type = "package")
 }
 
 parser_assignment <- function(call, env, block) {

tests/testthat/_snaps/object-from-call.md

@@ -0,0 +1,8 @@
+# finds package description
+
+    Code
+      blocks <- parse_file(file.path(path, "R/packages.R"))
+    Message
+      x packages.R:2: `@docType "package"` is deprecated.
+      i Please document "_PACKAGE" instead.
+

tests/testthat/empty/DESCRIPTION

@@ -1,3 +1,5 @@
 Package: empty
 Version: 1.0.0
 Encoding: UTF-8
+Title: Empty package
+Description: An empty package

tests/testthat/test-object-from-call.R

@@ -6,13 +6,30 @@ test_that("undocumentable things return null", {
 
 # data / package -------------------------------------------------------
 
+test_that("finds package description", {
+  path <- local_package_copy(test_path("empty"))
+  write_lines(path = file.path(path, "R/packages.R"), c(
+    "#' @docType package
+    NULL"
+  ))
+  expect_snapshot(blocks <- parse_file(file.path(path, "R/packages.R")))
+
+  expect_s3_class(blocks[[1]]$object, "package")
+
+  expect_equal(
+    block_get_tag_value(blocks[[1]], "aliases"),
+    "NULL empty empty-package"
+  )
+})
+
 test_that("finds package description", {
   obj <- call_to_object("_PACKAGE", file = test_path("testEagerData/R/a.r"))
   expect_s3_class(obj, "package")
   expect_equal(obj$alias, "_PACKAGE")
   expect_equal(obj$value$desc$get_field("Package"), "testEagerData")
 })
 
+
 test_that("finds datasets given by name", {
   obj <- call_to_object({
     df <- data.frame(x = 1, y = 2)

tests/testthat/test-rd-backref.R

@@ -2,7 +2,6 @@ test_that("Source reference is included as comment", {
   out <- roc_proc_text(rd_roclet(), "
     #' @name a
     #' @title a
-    #' @docType package
     NULL")[[1]]
 
   expect_match(out$get_rd("backref"), "^% Please edit documentation in ")
@@ -14,7 +13,6 @@ test_that("Explicit @backref is included as comment", {
     #' @title a
     #' @backref back/ref.file
     #' @backref root.file
-    #' @docType package
     NULL")[[1]]
 
   expect_equal(out$get_value("backref"), c("back/ref.file", "root.file"))