Improve color scale documentation (#4450)

* Improve color scale documentation

* more detailed documentation

* manual text wrap

Author: clauswilke

R/scale-colour.r

@@ -1,9 +1,31 @@
 #' Continuous and binned colour scales
 #'
-#' Colour scales for continuous data default to the values of the
-#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options. These
-#' [options()] default to `"gradient"` (i.e., [scale_colour_gradient()] and
-#' [scale_fill_gradient()])
+#' The scales `scale_colour_continuous()` and `scale_fill_continuous()` are
+#' the default colour scales ggplot2 uses when continuous data values are
+#' mapped onto the `colour` or `fill` aesthetics, respectively. The scales
+#' `scale_colour_binned()` and `scale_fill_binned()` are equivalent scale
+#' functions that assign discrete color bins to the continuous values
+#' instead of using a continuous color spectrum.
+#'
+#' All these colour scales use the [options()] mechanism to determine
+#' default settings. Continuous colour scales default to the values of the
+#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options, and
+#' binned colour scales default to the values of the `ggplot2.binned.colour`
+#' and `ggplot2.binned.fill` options. These option values default to
+#' `"gradient"`, which means that the scale functions actually used are
+#' [scale_colour_gradient()]/[scale_fill_gradient()] for continuous scales and
+#' [scale_colour_steps()]/[scale_fill_steps()] for binned scales.
+#' Alternative option values are `"viridis"` or a different scale function.
+#' See description of the `type` argument for details.
+#'
+#' Note that the binned colour scales will use the settings of
+#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` as fallback,
+#' respectively, if `ggplot2.binned.colour` or `ggplot2.binned.fill` are
+#' not set.
+#'
+#' These scale functions are meant to provide simple defaults. If
+#' you want to manually set the colors of a scale, consider using
+#' [scale_colour_gradient()] or [scale_colour_steps()].
 #'
 #' @param ... Additional parameters passed on to the scale type
 #' @param type One of the following:
@@ -13,7 +35,7 @@
 #' @seealso [scale_colour_gradient()], [scale_colour_viridis_c()],
 #'   [scale_colour_steps()], [scale_colour_viridis_b()], [scale_fill_gradient()],
 #'   [scale_fill_viridis_c()], [scale_fill_steps()], and [scale_fill_viridis_b()]
-#' @export
+#' @family colour scales
 #' @rdname scale_colour_continuous
 #' @section Color Blindness:
 #' Many color palettes derived from RGB combinations (like the "rainbow" color
@@ -40,6 +62,17 @@
 #' # The above are equivalent to
 #' v + scale_fill_gradient()
 #' v + scale_fill_viridis_c()
+#'
+#' # To make a binned version of this plot
+#' v + scale_fill_binned(type = "viridis")
+#'
+#' # Set a different default scale using the options
+#' # mechanism
+#' tmp <- getOption("ggplot2.continuous.fill") # store current setting
+#' options(ggplot2.continuous.fill = scale_fill_distiller)
+#' v
+#' options(ggplot2.continuous.fill = tmp) # restore previous setting
+#' @export
 scale_colour_continuous <- function(...,
                                     type = getOption("ggplot2.continuous.colour", default = "gradient")) {
   if (is.function(type)) {
@@ -70,7 +103,6 @@ scale_fill_continuous <- function(...,
 
 #' @export
 #' @rdname scale_colour_continuous
-#' @usage NULL
 scale_colour_binned <- function(...,
                                 type = getOption("ggplot2.binned.colour", default = getOption("ggplot2.continuous.colour", default = "gradient"))) {
   if (is.function(type)) {
@@ -86,7 +118,6 @@ scale_colour_binned <- function(...,
 
 #' @export
 #' @rdname scale_colour_continuous
-#' @usage NULL
 scale_fill_binned <- function(...,
                               type = getOption("ggplot2.binned.fill", default = getOption("ggplot2.continuous.fill", default = "gradient"))) {
   if (is.function(type)) {

R/scale-gradient.r

@@ -2,7 +2,8 @@
 #'
 #' `scale_*_gradient` creates a two colour gradient (low-high),
 #' `scale_*_gradient2` creates a diverging colour gradient (low-mid-high),
-#' `scale_*_gradientn` creates a n-colour gradient.
+#' `scale_*_gradientn` creates a n-colour gradient. For binned variants of
+#' these scales, see the [color steps][scale_colour_steps] scales.
 #'
 #' Default colours are generated with \pkg{munsell} and
 #' `mnsl(c("2.5PB 2/4", "2.5PB 7/10"))`. Generally, for continuous
@@ -17,7 +18,7 @@
 #'   colour bar, or `"legend"` for discrete colour legend.
 #' @inheritDotParams continuous_scale -na.value -guide -aesthetics
 #' @seealso [scales::seq_gradient_pal()] for details on underlying
-#'   palette
+#'   palette, [scale_colour_steps()] for binned variants of these scales.
 #' @family colour scales
 #' @rdname scale_gradient
 #' @export

R/scale-steps.R

@@ -16,7 +16,7 @@
 #' @inheritDotParams binned_scale -aesthetics -scale_name -palette -na.value -guide -rescaler
 #'
 #' @seealso [scales::seq_gradient_pal()] for details on underlying
-#'   palette
+#'   palette, [scale_colour_gradient()] for continuous scales without binning.
 #' @family colour scales
 #' @export
 #' @examples