From 3f32c7a9a890941314522a5f377f5e8756cccc6f Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Wed, 28 Feb 2024 14:52:03 +0100
Subject: [PATCH] Cover interactions in `coord_flip()`

---
 R/coord-flip.R    | 13 +++++++++++++
 man/coord_flip.Rd | 14 ++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/R/coord-flip.R b/R/coord-flip.R
index 1f3848fb8a..7ff519d15c 100644
--- a/R/coord-flip.R
+++ b/R/coord-flip.R
@@ -11,6 +11,19 @@
 #' the `orientation` setting, and converting the display of y conditional on x,
 #' to x conditional on y.
 #'
+#' @details
+#' Coordinate systems interact with many parts of the plotting system. You can
+#' expect the following for `coord_flip()`:
+#'
+#' * It does *not* change the facet order in `facet_grid()` or `facet_wrap()`.
+#' * The `scale_x_*()` functions apply to the vertical direction,
+#'   whereas `scale_y_*()` functions apply to the horizontal direction. The
+#'   same holds for the `xlim` and `ylim` arguments of `coord_flip()` and the
+#'   `xlim()` and `ylim()` functions.
+#' * The x-axis theme settings, such as `axis.line.x` apply to the horizontal
+#'   direction. The y-axis theme settings, such as `axis.text.y` apply to the
+#'   vertical direction.
+#'
 #' @export
 #' @inheritParams coord_cartesian
 #' @examples
diff --git a/man/coord_flip.Rd b/man/coord_flip.Rd
index 6f86fa4eda..be69644cf0 100644
--- a/man/coord_flip.Rd
+++ b/man/coord_flip.Rd
@@ -33,6 +33,20 @@ be replaced by swapping the x and y aesthetics, or optionally setting the
 the \code{orientation} setting, and converting the display of y conditional on x,
 to x conditional on y.
 }
+\details{
+Coordinate systems interact with many parts of the plotting system. You can
+expect the following for \code{coord_flip()}:
+\itemize{
+\item It does \emph{not} change the facet order in \code{facet_grid()} or \code{facet_wrap()}.
+\item The \verb{scale_x_*()} functions apply to the vertical direction,
+whereas \verb{scale_y_*()} functions apply to the horizontal direction. The
+same holds for the \code{xlim} and \code{ylim} arguments of \code{coord_flip()} and the
+\code{xlim()} and \code{ylim()} functions.
+\item The x-axis theme settings, such as \code{axis.line.x} apply to the horizontal
+direction. The y-axis theme settings, such as \code{axis.text.y} apply to the
+vertical direction.
+}
+}
 \examples{
 # The preferred method of creating horizontal instead of vertical boxplots
 ggplot(diamonds, aes(price, cut)) +