📝 Mention (fill_)alpha() in theme element docs (#6283)

* mention alpha/fill_alpha in params

* sprinkle comments in examples

Author: teunbrand

R/theme-elements.R

@@ -14,8 +14,10 @@
 #' `margin()`, `margin_part()` and `margin_auto()` are all used to specify the
 #' margins of elements.
 #'
-#' @param fill Fill colour.
+#' @param fill Fill colour. `fill_alpha()` can be used to set the transparency
+#'   of the fill.
 #' @param colour,color Line/border colour. Color is an alias for colour.
+#'   `alpha()` can be used to set the transparency of the colour.
 #' @param linewidth,borderwidth Line/border size in mm.
 #' @param size,fontsize text size in pts.
 #' @param arrow.fill Fill colour for arrows.
@@ -26,17 +28,21 @@
 #'   calculating final element state.
 #' @return An S3 object of class `element`, `rel`, or `margin`.
 #' @examples
+#' # A standard plot
 #' plot <- ggplot(mpg, aes(displ, hwy)) + geom_point()
 #'
+#' # Turning off theme elements by setting them to blank
 #' plot + theme(
 #'   panel.background = element_blank(),
 #'   axis.text = element_blank()
 #' )
 #'
+#' # Text adjustments
 #' plot + theme(
 #'   axis.text = element_text(colour = "red", size = rel(1.5))
 #' )
 #'
+#' # Turning on the axis line with an arrow
 #' plot + theme(
 #'   axis.line = element_line(arrow = arrow())
 #' )