Document missing elements in theme()

NAMESPACE

@@ -737,6 +737,7 @@ export(theme_sub_axis_top)
 export(theme_sub_axis_x)
 export(theme_sub_axis_y)
 export(theme_sub_legend)
+export(theme_sub_palette)
 export(theme_sub_panel)
 export(theme_sub_plot)
 export(theme_sub_strip)

NEWS.md

@@ -33,6 +33,10 @@
 * New `position_dodge2(group.row)` argument that can be set to `"many"` to
   dodge groups with more than one row, such as in `geom_violin()` 
   (@teunbrand, #6663)
+* `palette.{aes}.discrete` and `palette.{aes}.continuous` are now documented
+  in `theme()` and have a new helper `theme_sub_palette()`.
+  `strip.position.x` and `strip.position.y` are also documented and work
+  with `theme_sub_strip()` (@arcresu, #6829).
 
 # ggplot2 4.0.2
 

R/theme-sub.R

@@ -127,6 +127,18 @@ theme_sub_legend <- function(
   subtheme(find_args(), "legend.")
 }
 
+#' @export
+#' @describeIn subtheme Theme specification for palettes.
+theme_sub_palette <- function(..., colour.continuous, colour.discrete,
+                              fill.continuous, fill.discrete, alpha.continuous,
+                              alpha.discrete, linewidth.continuous,
+                              linewidth.discrete, size.continuous,
+                              size.discrete, shape.continuous, shape.discrete,
+                              linetype.continuous, linetype.discrete) {
+  warn_dots_empty()
+  subtheme(find_args(), "palette.")
+}
+
 #' @export
 #' @describeIn subtheme Theme specification for the panels.
 theme_sub_panel <- function(..., background, border,
@@ -149,7 +161,8 @@ theme_sub_plot <- function(..., background, title, title.position, subtitle, cap
 #' @export
 #' @describeIn subtheme Theme specification for facet strips.
 theme_sub_strip <- function(..., background, background.x, background.y, clip,
-                            placement, text, text.x, text.x.bottom, text.x.top,
+                            placement, placement.x, placement.y, text, text.x,
+                            text.x.bottom, text.x.top,
                             text.y, text.y.left, text.y.right,
                             switch.pad.grid, switch.pad.wrap) {
   warn_dots_empty()
@@ -160,7 +173,7 @@ subtheme_param_doc <- function() {
   funs <- list(
     theme_sub_axis, theme_sub_axis_x, theme_sub_axis_y, theme_sub_axis_bottom,
     theme_sub_axis_top, theme_sub_axis_left, theme_sub_axis_right, theme_sub_legend,
-    theme_sub_panel, theme_sub_plot, theme_sub_strip
+    theme_sub_panel, theme_sub_plot, theme_sub_strip, theme_sub_palette
   )
   args <- sort(unique(unlist(lapply(funs, fn_fmls_names), use.names = FALSE)))
   args <- setdiff(args, "...")

R/theme.R

@@ -132,6 +132,21 @@
 #' @param legend.box.spacing The spacing between the plotting area and the
 #'   legend box (`unit`); inherits from `spacing`.
 #'
+#' @param palette.colour.discrete,palette.colour.continuous,palette.fill.discrete,palette.fill.continuous
+#'   default palettes for the colour and fill aesthetics to use for discrete or
+#'   continuous data. Can be a character vector of colours or a palette function
+#'   such as [scales::pal_hue()]. `palette.fill.discrete` inherits from
+#'   palette.colour.discrete` and `palette.fill.continuous` inherits from
+#'   `palette.colour.continuous`.
+#' @param palette.alpha.discrete,palette.linewidth.discrete,palette.size.discrete,palette.shape.discrete,palette.linetype.discrete
+#'   default palette to use for discrete scales for the corresponding aesthetic.
+#'   See the `palette` parameter of [discrete_scale()] and
+#'   `vignette("ggplot2-specs")` for allowed values.
+#' @param palette.alpha.continuous,palette.linewidth.continuous,palette.size.continuous,palette.shape.continuous,palette.linetype.continuous
+#'   default palette to use for continuous scales for the corresponding aesthetic.
+#'   See the `palette` parameter of [continuous_scale()] and
+#'   `vignette("ggplot2-specs")` for allowed values.
+#'
 #' @param panel.background background of plotting area, drawn underneath plot
 #'   ([element_rect()]; inherits from `rect`)
 #' @param panel.border border around plotting area, drawn on top of plot so that
@@ -192,9 +207,11 @@
 #'   inherits from `rect`). Horizontal facet background (`strip.background.x`)
 #'   & vertical facet background (`strip.background.y`) inherit from
 #'   `strip.background` or can be specified separately
-#' @param strip.placement placement of strip with respect to axes,
-#'    either "inside" or "outside". Only important when axes and strips are
-#'    on the same side of the plot.
+#' @param strip.placement,strip.placement.x,strip.placement.y
+#'    placement of strip with respect to axes, either "inside" or "outside".
+#'    Only important when axes and strips are on the same side of the plot.
+#'    Horizontal (`strip.placement.x`) & vertical (`strip.placement.y`) placements
+#'    inherit from `strip.placement` or can be specified separately
 #' @param strip.clip should strip background edges and strip labels be clipped
 #'   to the extend of the strip background? Options are `"on"` to clip, `"off"`
 #'   to disable clipping or `"inherit"` (default) to take the clipping setting
@@ -444,6 +461,20 @@ theme <- function(...,
                   legend.box.margin,
                   legend.box.background,
                   legend.box.spacing,
+                  palette.colour.discrete,
+                  palette.colour.continuous,
+                  palette.fill.discrete,
+                  palette.fill.continuous,
+                  palette.alpha.discrete,
+                  palette.alpha.continuous,
+                  palette.linewidth.discrete,
+                  palette.linewidth.continuous,
+                  palette.size.discrete,
+                  palette.size.continuous,
+                  palette.shape.discrete,
+                  palette.shape.continuous,
+                  palette.linetype.discrete,
+                  palette.linetype.continuous,
                   panel.background,
                   panel.border,
                   panel.spacing,
@@ -474,6 +505,8 @@ theme <- function(...,
                   strip.background.y,
                   strip.clip,
                   strip.placement,
+                  strip.placement.x,
+                  strip.placement.y,
                   strip.text,
                   strip.text.x,
                   strip.text.x.bottom,

tests/testthat/test-theme-sub.R

@@ -13,6 +13,8 @@ test_that("subtheme functions rename arguments as intended", {
   expect_equal(theme_sub_axis_left(ticks = line),   theme(axis.ticks.y.left = line))
   expect_equal(theme_sub_axis_right(ticks = line),  theme(axis.ticks.y.right = line))
   expect_equal(theme_sub_legend(key = rect),        theme(legend.key = rect))
+  expect_equal(theme_sub_palette(fill.discrete = c()),
+                                                    theme(palette.fill.discrete = c()))
   expect_equal(theme_sub_panel(border = rect),      theme(panel.border = rect))
   expect_equal(theme_sub_plot(background = rect),   theme(plot.background = rect))
   expect_equal(theme_sub_strip(background = rect),  theme(strip.background = rect))
@@ -41,6 +43,7 @@ test_that("theme elements are covered in `theme_sub_*()` functions", {
   fmls <- c(fmls, paste0("axis.",   fn_fmls_names(theme_sub_axis_right), ".y.right"))
   fmls <- c(fmls, paste0("legend.", fn_fmls_names(theme_sub_legend)))
   fmls <- c(fmls, paste0("plot.",   fn_fmls_names(theme_sub_plot)))
+  fmls <- c(fmls, paste0("palette.",fn_fmls_names(theme_sub_palette)))
   fmls <- c(fmls, paste0("panel.",  fn_fmls_names(theme_sub_panel)))
   fmls <- c(fmls, paste0("strip.",  fn_fmls_names(theme_sub_strip)))
 

tests/testthat/test-theme.R

@@ -693,3 +693,14 @@ test_that("legends are placed correctly when using stretchy spacing", {
     p + theme(legend.position = "top", legend.spacing.x = unit(1, "null"))
   )
 })
+
+test_that("all theme elements are documented", {
+  all_elems <- names(.element_tree)
+  doc_fmls <- fn_fmls_names(theme)
+  missing_elems <- setdiff(all_elems, doc_fmls)
+
+  expect(length(missing_elems) == 0, c(
+    "Expected all elements in `.element_tree` to have corresponding parameters in `theme()`.",
+    sprintf("Element is missing from theme(): %s", paste(missing_elems))
+  ))
+})