update theme documentation reference links & clarify differences between theme_set and theme_update() (#3782)

* add complete themes reference link to theme docs, clarify difference between theme_set() and theme_update() with examples, references #3294

* fixes to comply with PR review. add theme_replace in bullet list summary, merge all update/set/replace examples into one section, references #3294

* theme_replace example made similar to theme_update example for better comparison, references #3294

* fix theme_update and theme_replace example to better show differences, references #3294

Author: Ryo-N7

R/theme-current.R

@@ -4,28 +4,36 @@ NULL
 
 #' Get, set, and modify the active theme
 #'
-#' The current/active theme is automatically applied to every plot you draw.
-#' Use `theme_get` to get the current theme, and `theme_set` to
-#' completely override it. `theme_update` and `theme_replace` are
-#' shorthands for changing individual elements.
+#' The current/active theme (see [theme()]) is automatically applied to every
+#' plot you draw. Use `theme_get` to get the current theme, and `theme_set` to
+#' completely override it. `theme_update` and `theme_replace` are shorthands for
+#' changing individual elements.
 #'
 #' @section Adding on to a theme:
 #'
-#' `+` and `%+replace%` can be used to modify elements in themes.
+#'   `+` and `%+replace%` can be used to modify elements in themes.
 #'
-#' `+` updates the elements of e1 that differ from elements specified (not
-#' NULL) in e2. Thus this operator can be used to incrementally add or modify
-#' attributes of a ggplot theme.
+#'   `+` updates the elements of e1 that differ from elements specified (not
+#'   NULL) in e2. Thus this operator can be used to incrementally add or modify
+#'   attributes of a ggplot theme.
 #'
-#' In contrast, `%+replace%` replaces the entire element; any element of
-#' a theme not specified in e2 will not be present in the resulting theme (i.e.
-#' NULL). Thus this operator can be used to overwrite an entire theme.
+#'   In contrast, `%+replace%` replaces the entire element; any element of a
+#'   theme not specified in e2 will not be present in the resulting theme (i.e.
+#'   NULL). Thus this operator can be used to overwrite an entire theme.
 #'
-#' `theme_update` uses the `+` operator, so that any unspecified
-#' values in the theme element will default to the values they are set in the
-#' theme. `theme_replace` uses `%+replace%` to completely replace
-#' the element, so any unspecified values will overwrite the current value in
-#' the theme with `NULL`s.
+#'   `theme_update` uses the `+` operator, so that any unspecified values in the
+#'   theme element will default to the values they are set in the theme.
+#'   `theme_replace` uses `%+replace%` to completely replace the element, so any
+#'   unspecified values will overwrite the current value in the theme with
+#'   `NULL`.
+#'
+#'   In summary, the main differences between `theme_set()`, `theme_update()`,
+#'   and `theme_replace()` are:
+#'   * `theme_set()` completely overrides the current theme.
+#'   * `theme_update()` modifies a particular element of the current theme
+#'   using the `+` operator.
+#'   * `theme_replace()` modifies a particular element of the current theme
+#'   using the `%+replace%` operator.
 #'
 #' @param ... named list of theme settings
 #' @param e1,e2 Theme and element to combine
@@ -40,11 +48,23 @@ NULL
 #' p
 #'
 #' # Use theme_set() to completely override the current theme.
+#' # theme_update() and theme_replace() are similar except they
+#' # apply directly to the current/active theme.
+#' # theme_update() modifies a particular element of the current theme.
 #' # Here we have the old theme so we can later restore it.
 #' # Note that the theme is applied when the plot is drawn, not
 #' # when it is created.
 #' old <- theme_set(theme_bw())
 #' p
+#'
+#' theme_set(old)
+#' theme_update(panel.grid.minor = element_line(colour = "red"))
+#' p
+#'
+#' theme_set(old)
+#' theme_replace(panel.grid.minor = element_line(colour = "red"))
+#' p
+#'
 #' theme_set(old)
 #' p
 #'
@@ -62,8 +82,6 @@ NULL
 #'   theme(text = element_text(family = "Times"))
 #' rep_el$text
 #'
-#' # theme_update() and theme_replace() are similar except they
-#' # apply directly to the current/active theme.
 theme_get <- function() {
   ggplot_global$theme_current
 }

R/theme.r

@@ -1,12 +1,13 @@
 #' Modify components of a theme
 #'
-#' Themes are a powerful way to customize the non-data components of your
-#' plots: i.e. titles, labels, fonts, background, gridlines, and legends.
-#' Themes can be used to give plots a consistent customized look.
-#' Modify a single plot's theme using `theme()`; see [theme_update()] if
-#' you want modify the active theme, to affect all subsequent plots. Theme
-#' elements are documented together according to inheritance, read more
-#' about theme inheritance below.
+#' Themes are a powerful way to customize the non-data components of your plots:
+#' i.e. titles, labels, fonts, background, gridlines, and legends. Themes can be
+#' used to give plots a consistent customized look. Modify a single plot's theme
+#' using `theme()`; see [theme_update()] if you want modify the active theme, to
+#' affect all subsequent plots. Use the themes available in [complete
+#' themes][theme_bw] if you would like to use a complete theme such as
+#' `theme_bw()`, `theme_minimal()`, and more. Theme elements are documented
+#' together according to inheritance, read more about theme inheritance below.
 #'
 #' @section Theme inheritance:
 #' Theme elements inherit properties from other theme elements hierarchically.