From d180248704d4e2ef8e3568c8806eb83b97ac50d9 Mon Sep 17 00:00:00 2001
From: Arthur Yip <5713411+ahcyip@users.noreply.github.com>
Date: Mon, 4 Sep 2023 01:26:02 -0600
Subject: [PATCH] Update documentation and example in scale-brewer.R to reflect
 scale_*_distiller's non-intuitive "direction" (#5381)

* Update scale-brewer.R

Capturing in documentation that scale_*_distiller has a non-intuitive default direction = -1, and that to reverse, user needs to specify direction = 1

Source:
https://github.com/tidyverse/ggplot2/issues/1439
https://github.com/tidyverse/ggplot2/issues/4444

* Move comment from Details to Note

* Document

---------

Co-authored-by: yutannihilation <yutannihilation@users.noreply.github.com>
---
 R/scale-brewer.R    | 7 +++++--
 man/scale_brewer.Rd | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/R/scale-brewer.R b/R/scale-brewer.R
index 72264f98f4..2bf583961a 100644
--- a/R/scale-brewer.R
+++ b/R/scale-brewer.R
@@ -8,8 +8,9 @@
 #'
 #' @note
 #' The `distiller` scales extend `brewer` scales by smoothly
-#' interpolating 7 colours from any palette to a continuous scale. The `fermenter`
-#' scales provide binned versions of the `brewer` scales.
+#' interpolating 7 colours from any palette to a continuous scale. 
+#' The `distiller` scales have a default direction = -1. To reverse, use direction = 1.
+#' The `fermenter` scales provide binned versions of the `brewer` scales.
 #'
 #' @details
 #' The `brewer` scales were carefully designed and tested on discrete data.
@@ -75,6 +76,8 @@
 #' v
 #' v + scale_fill_distiller()
 #' v + scale_fill_distiller(palette = "Spectral")
+#' # the order of colour can be reversed, but with scale_*_distiller(), the default direction = -1, so to reverse, use direction = 1.
+#' v + scale_fill_distiller(palette = "Spectral", direction = 1)
 #'
 #' # or use blender variants to discretise continuous data
 #' v + scale_fill_fermenter()
diff --git a/man/scale_brewer.Rd b/man/scale_brewer.Rd
index c71599ca40..073d3f0d02 100644
--- a/man/scale_brewer.Rd
+++ b/man/scale_brewer.Rd
@@ -119,8 +119,9 @@ look good. Your mileage may vary.
 }
 \note{
 The \code{distiller} scales extend \code{brewer} scales by smoothly
-interpolating 7 colours from any palette to a continuous scale. The \code{fermenter}
-scales provide binned versions of the \code{brewer} scales.
+interpolating 7 colours from any palette to a continuous scale.
+The \code{distiller} scales have a default direction = -1. To reverse, use direction = 1.
+The \code{fermenter} scales provide binned versions of the \code{brewer} scales.
 }
 \section{Palettes}{
 
@@ -168,6 +169,8 @@ v <- ggplot(faithfuld) +
 v
 v + scale_fill_distiller()
 v + scale_fill_distiller(palette = "Spectral")
+# the order of colour can be reversed, but with scale_*_distiller(), the default direction = -1, so to reverse, use direction = 1.
+v + scale_fill_distiller(palette = "Spectral", direction = 1)
 
 # or use blender variants to discretise continuous data
 v + scale_fill_fermenter()