Warn on unsupported geoms in annotate()

NEWS.md

@@ -1,5 +1,8 @@
 # ggplot2 (development version)
 
+* `annotate()` now documents unsupported geoms (`geom_abline()`, `geom_hline()`
+  and `geom_vline()`), and warns when they are requested (@mikmart, #4719)
+
 * `presidential` dataset now includes Trump's presidency (@bkmgit, #4703).
 
 * referring to `x` in backquoted expressions with `label_bquote()` is no longer

R/annotation.r

@@ -11,6 +11,10 @@
 #' set. This means that layers created with this function will never
 #' affect the legend.
 #'
+#' @section Unsupported geoms:
+#' Due to their special nature, reference line geoms [geom_abline()],
+#' [geom_hline()], and [geom_vline()] can't be used with [annotate()].
+#' You can use these geoms directory for annotations.
 #' @param geom name of geom to use for annotation
 #' @param x,y,xmin,ymin,xmax,ymax,xend,yend positioning aesthetics -
 #'   you must specify at least one of these.
@@ -38,6 +42,13 @@ annotate <- function(geom, x = NULL, y = NULL, xmin = NULL, xmax = NULL,
                      ymin = NULL, ymax = NULL, xend = NULL, yend = NULL, ...,
                      na.rm = FALSE) {
 
+  if (geom %in% c("abline", "hline", "vline")) {
+    warn(c(
+      glue("`annotate()` does not support `geom = \"{geom}\"`."),
+      i = glue("Please use `geom_{geom}()` directly instead.")
+    ))
+  }
+
   position <- compact(list(
     x = x, xmin = xmin, xmax = xmax, xend = xend,
     y = y, ymin = ymin, ymax = ymax, yend = yend

tests/testthat/_snaps/annotate.md

@@ -0,0 +1,5 @@
+# unsupported geoms signal a warning (#4719)
+
+    `annotate()` does not support `geom = "hline"`.
+    i Please use `geom_hline()` directly instead.
+

tests/testthat/test-annotate.r

@@ -48,3 +48,7 @@ test_that("annotation_* has dummy data assigned and don't inherit aes", {
   expect_false(map$inherit.aes)
   expect_false(raster$inherit.aes)
 })
+
+test_that("unsupported geoms signal a warning (#4719)", {
+  expect_snapshot_warning(annotate("hline", yintercept = 0))
+})