diff --git a/NEWS.md b/NEWS.md index 3f5acf023..904e8f6ce 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ # roxygen2 (development version) +* roxygen2 now does not fail for `@description NULL` and `@details NULL`. + Instead, these tags are ignored, except for `@description NULL` in + package level documentation, where it can be used to suppress the + auto-generated Description section (#1008). + # roxygen2 7.0.2 * `\example{}` escaping has been improved (again!) so that special escapes diff --git a/R/rd.R b/R/rd.R index facc60024..462a1e9a2 100644 --- a/R/rd.R +++ b/R/rd.R @@ -191,7 +191,8 @@ topics_add_default_description <- function(topics) { next # rexport manually generates a own description, so don't need to - if (!topic$has_section("reexport")) { + if (!topic$has_section("reexport") && + !identical(topic$get_value("docType"), "package")) { topic$add(rd_section("description", topic$get_value("title"))) } } diff --git a/R/topic.R b/R/topic.R index d82b007ae..a50e4a3ed 100644 --- a/R/topic.R +++ b/R/topic.R @@ -148,6 +148,7 @@ RoxyTopic <- R6::R6Class("RoxyTopic", public = list( #' @param section [rd_section] object to add. add_section = function(section, overwrite = FALSE) { + if (is.null(section)) return() type <- section$type if (self$has_section(type) && !overwrite) { section <- merge(self$get_section(type), section) diff --git a/tests/testthat/test-rd.R b/tests/testthat/test-rd.R index d7f746d98..1ae7e5e02 100644 --- a/tests/testthat/test-rd.R +++ b/tests/testthat/test-rd.R @@ -59,6 +59,85 @@ test_that("documenting NA gives useful error message (#194)", { ) }) +test_that("@description NULL", { + # Just ignore in this case + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' + #' @description NULL + #' @format NULL + foobar <- 1:10 + ") + expect_identical(out[[1]]$get_value("description"), "Title") + + # Still ignore + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' @description NULL + #' @description desc + #' @format NULL + foobar <- 1:10 + ") + expect_identical(out[[1]]$get_value("description"), "desc") + + # Still ignore for objects as well + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' @description NULL + #' @format NULL + foobar <- 1:10 + ") + expect_identical(out[[1]]$get_value("description"), "Title") + + # But drop for package docs + with_mock( + `roxygen2::read.description` = function(...) + list(Package = "roxygen_devtest", + Title = "Package Title", + Description = "Package description."), + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' + #' @docType package + #' @description NULL + #' @name pkg + '_PACKAGE' + ") + ) + expect_null(out[[1]]$get_value("description")) +}) + +test_that("@details NULL", { + # Just ignore in this case + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' + #' @details NULL + #' @format NULL + foobar <- 1:10 + ") + expect_null(out[[1]]$get_value("details")) + + # Still ignore + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' @details NULL + #' @details desc + #' @format NULL + foobar <- 1:10 + ") + expect_identical(out[[1]]$get_value("details"), "desc") + + # Still ignore for objects as well + out <- roxygen2::roc_proc_text(roxygen2::rd_roclet(), " + #' Title + #' @details NULL + #' @format NULL + foobar <- 1:10 + ") + expect_null(out[[1]]$get_value("details")) +}) + # UTF-8 ------------------------------------------------------------------- test_that("can generate nonASCII document", {