Document strip.placement.{x,y} (#6846)

* Add snapshot test for theme params

* Document strip.placement.{x,y}

* Add news bullet

Author: arcresu

NEWS.md

@@ -33,6 +33,9 @@
 * 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)
+* `theme(strip.placement.x)` and `theme(strip.placement.y)` can be used for more
+  granular control of strip placement when facetting. These have existed for some
+  time but were not previously documented (@arcresu, #6827).
 
 # ggplot2 4.0.2
 

R/theme-sub.R

@@ -149,7 +149,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()

R/theme.R

@@ -192,9 +192,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
@@ -474,6 +476,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,

man/subtheme.Rd

@@ -58,3 +58,16 @@
 
     Unknown arguments to `element_text()`: `italic`, `fontweight`, and `fontwidth`.
 
+# all expected theme elements are documented
+
+    Code
+      extra_elements
+    Output
+       [1] "palette.colour.discrete"      "palette.colour.continuous"   
+       [3] "palette.fill.discrete"        "palette.fill.continuous"     
+       [5] "palette.alpha.discrete"       "palette.alpha.continuous"    
+       [7] "palette.linewidth.discrete"   "palette.linewidth.continuous"
+       [9] "palette.size.discrete"        "palette.size.continuous"     
+      [11] "palette.shape.discrete"       "palette.shape.continuous"    
+      [13] "palette.linetype.discrete"    "palette.linetype.continuous" 
+

man/theme.Rd

@@ -693,3 +693,8 @@ test_that("legends are placed correctly when using stretchy spacing", {
     p + theme(legend.position = "top", legend.spacing.x = unit(1, "null"))
   )
 })
+
+test_that("all expected theme elements are documented", {
+  extra_elements <- setdiff(names(.element_tree), fn_fmls_names(theme))
+  expect_snapshot(extra_elements)
+})