Improve color scale documentation

R/scale-colour.r

@@ -3,7 +3,12 @@
 #' 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()])
+#' [scale_fill_gradient()]). Note that both continuous and binned scales
+#' are configured with the same options values. In other words,
+#' the option `ggplot2.continuous.colour` controls the behavior of both
+#' `scale_colour_continuous()` and `scale_colour_binned()`. To manually set
+#' the colors of the 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 +18,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 +45,10 @@
 #' # 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")
+#' @export
 scale_colour_continuous <- function(...,
                                     type = getOption("ggplot2.continuous.colour", default = "gradient")) {
   if (is.function(type)) {
@@ -70,7 +79,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 +94,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