Centralise documentation for common layer arguments (#6730)

* collect universal arguments in separate Rd

* redirect `@inheritParams`

* canonise `orientation` arg

* replace `rd_orientation()` with `@inheritSection`

* canonise line params

* canonise `arrow` param

* move docs to `docs_layer.R`

Author: teunbrand

R/annotation.R

@@ -18,8 +18,7 @@
 #' @param geom name of geom to use for annotation
 #' @param x,y,xmin,ymin,xmax,ymax,xend,yend positioning aesthetics -
 #'   you must specify at least one of these.
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @seealso
 #' The `r link_book("custom annotations section", "annotations#sec-custom-annotations")`
 #' @export

R/docs_layer.R

@@ -1,3 +1,146 @@
+# Shared parameters -------------------------------------------------------
+
+#' @name shared_layer_parameters
+#' @title Shared layer parameters
+#' @description
+#' This is a central place for describing typical layer parameters.
+#' It prevents cluttered definitions all over the place.
+#'
+#' @param mapping
+#' Set of aesthetic mappings created by [aes()]. If specified and `inherit.aes =
+#' TRUE` (the default), it is combined with the default mapping at the top level
+#' of the plot. You must supply `mapping` if there is no plot mapping.
+#'
+#' @param data
+#' The data to be displayed in this layer. There are three options:
+#' * `NULL` (default): the data is inherited from the plot data as specified
+#'   in the call to [ggplot()].
+#' * A `data.frame`, or other object, will override the plot data. All objects
+#'   will be fortified to produce a data frame. See [fortify()] for which
+#'   variables will be created.
+#' * A `function` will be called with a single argument, the plot data. The return
+#'   value must be a `data.frame`, and will be used as the layer data. A
+#'   `function` can be created from a `formula` (e.g. `~ head(.x, 10)`).
+#'
+#' @param geom
+#' The geometric object to use to display the data for this layer. When using a
+#' `stat_*()` function to construct a layer, the `geom` argument can be used to
+#' override the default coupling between stats and geoms. The `geom` argument
+#' accepts the following:
+#' * A `Geom` ggproto subclass, for example `GeomPoint`.
+#' * A string naming the geom. To give the geom as a string, strip the
+#'   function name of the `geom_` prefix. For example, to use `geom_point()`,
+#'   give the geom as `"point"`.
+#' * For more information and other ways to specify the geom, see the
+#'   [layer geom][layer_geoms] documentation.
+#'
+#' @param stat
+#' The statistical transformation to use on the data for this layer. When using
+#' a `geom_*()` function to construct a layer, the `stat` argument can be used
+#' to override the default coupling between geoms and stats. The `stat` argument
+#' accepts the following:
+#' * A `Stat` ggproto subclass, for example `StatCount`.
+#' * A string naming the stat. To give the stat as a string, strip the
+#'   function name of the `stat_` prefix. For example, to use `stat_count()`,
+#'   give the stat as `"count"`.
+#' * For more information and other ways to specify the stat, see the
+#'   [layer stat][layer_stats] documentation.
+#'
+#' @param position
+#' A position adjustment to use on the data for this layer. This can be used in
+#' various ways, including to prevent overplotting and improving the display.
+#' The `position` argument accepts the following:
+#' * The result of calling a position function, such as `position_jitter()`.
+#'   This method allows for passing extra arguments to the position.
+#' * A string naming the position adjustment. To give the position as a
+#'   string, strip the function name of the `position_` prefix. For example, to
+#'   use `position_jitter()`, give the position as `"jitter"`.
+#' * For more information and other ways to specify the position, see the
+#'   [layer position][layer_positions] documentation.
+#'
+#' @param na.rm
+#' If `FALSE`, the default, missing values are removed with a warning. If
+#' `TRUE`, missing values are silently removed.
+#'
+#' @param show.legend
+#' Logical. Should this layer be included in the legends? `NA`, the default,
+#' includes if any aesthetics are mapped. `FALSE` never includes, and `TRUE`
+#' always includes. It can also be a named logical vector to finely select the
+#' aesthetics to display. To include legend keys for all levels, even when no
+#' data exists, use `TRUE`.  If `NA`, all levels are shown in legend, but
+#' unobserved levels are omitted.
+#'
+#' @param inherit.aes
+#' If `FALSE`, overrides the default aesthetics, rather than combining with
+#' them. This is most useful for helper functions that define both data and
+#' aesthetics and shouldn't inherit behaviour from the default plot
+#' specification, e.g. [annotation_borders()].
+#'
+#' @param ...
+#' Other arguments passed on to [layer()]'s `params` argument. These arguments
+#' broadly fall into one of 4 categories below. Notably, further arguments to
+#' the `position` argument, or aesthetics that are required can
+#'   *not* be passed through `...`. Unknown arguments that are not part of the 4
+#' categories below are ignored.
+#' * Static aesthetics that are not mapped to a scale, but are at a fixed
+#'   value and apply to the layer as a whole. For example, `colour = "red"` or
+#'   `linewidth = 3`. The geom's documentation has an **Aesthetics** section
+#'   that lists the available options. The 'required' aesthetics cannot be
+#'   passed on to the `params`. Please note that while passing unmapped
+#'   aesthetics as vectors is technically possible, the order and required
+#'   length is not guaranteed to be parallel to the input data.
+#' * When constructing a layer using
+#'   a `stat_*()` function, the `...` argument can be used to pass on parameters
+#'   to the `geom` part of the layer. An example of this is
+#'   `stat_density(geom = "area", outline.type = "both")`. The geom's
+#'   documentation lists which parameters it can accept.
+#' * Inversely, when constructing a layer using a
+#'   `geom_*()` function, the `...` argument can be used to pass on parameters
+#'   to the `stat` part of the layer. An example of this is
+#'   `geom_area(stat = "density", adjust = 0.5)`. The stat's documentation lists
+#'   which parameters it can accept.
+#' * The `key_glyph` argument of [`layer()`] may also be passed on through
+#'   `...`. This can be one of the functions described as
+#'   [key glyphs][draw_key], to change the display of the layer in the legend.
+#'
+#' @param lineend
+#' Line end style, one of `"round"`, `"butt"` or `"square"`.
+#'
+#' @param linejoin
+#' Line join style, one of `"round"`, `"mitre"` or `"bevel"`.
+#'
+#' @param linemitre
+#' Line mitre limit, a number greater  than 1.
+#'
+#' @param arrow
+#' Arrow specification. Can be created by [grid::arrow()] or `NULL` to not draw
+#' an arrow.
+#'
+#' @param arrow.fill
+#' Fill colour to use for closed arrowheads. `NULL` means use `colour`
+#' aesthetic.
+#'
+#' @param orientation
+#' The orientation of the layer. The default (`NA`) automatically determines the
+#' orientation from the aesthetic mapping. In the rare event that this fails it
+#' can be given explicitly by setting `orientation` to either `"x"` or `"y"`.
+#' See the *Orientation* section for more detail.
+#'
+#' @section Orientation:
+#' This geom treats each axis differently and, thus, can have two
+#' orientations. Often the orientation is easy to deduce from a combination of
+#' the given mappings and the types of positional scales in use. Thus, ggplot2
+#' will by default try to guess which orientation the layer should have. Under
+#' rare circumstances, the orientation is ambiguous and guessing may fail. In
+#' that case the orientation can be specified directly using the `orientation`
+#' parameter, which can be either `"x"` or `"y"`. The value gives the axis that
+#' the geom should run along, `"x"` being the default orientation you would
+#' expect for the geom.
+#'
+#' @keywords internal
+#' @aliases NULL
+NULL
+
 # Geoms -------------------------------------------------------------------
 
 #' @title

R/geom-abline.R

@@ -31,8 +31,7 @@ NULL
 #'
 #' @seealso See [geom_segment()] for a more general approach to
 #'   adding straight line segments to a plot.
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @param mapping Set of aesthetic mappings created by [aes()].
 #' @param xintercept,yintercept,slope,intercept Parameters that control the
 #'   position of the line. If these are set, `data`, `mapping` and

R/geom-bar.R

@@ -66,7 +66,7 @@ GeomBar <- ggproto(
 #' [position_fill()] shows relative proportions at each `x` by stacking the
 #' bars and then standardising each bar to have the same height.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @aesthetics GeomBar
 #' @aesthetics GeomCol
@@ -76,12 +76,7 @@ GeomBar <- ggproto(
 #'   [position_dodge()] and [position_dodge2()] for creating side-by-side
 #'   bar charts.
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @param orientation The orientation of the layer. The default (`NA`)
-#' automatically determines the orientation from the aesthetic mapping. In the
-#' rare event that this fails it can be given explicitly by setting `orientation`
-#' to either `"x"` or `"y"`. See the *Orientation* section for more detail.
+#' @inheritParams shared_layer_parameters
 #' @param just Adjustment for column placement. Set to `0.5` by default, meaning
 #'   that columns will be centered about axis breaks. Set to `0` or `1` to place
 #'   columns to the left/right of axis breaks. Note that this argument may have
@@ -90,8 +85,6 @@ GeomBar <- ggproto(
 #' @param geom,stat Override the default connection between `geom_bar()` and
 #'   `stat_count()`. For more information about overriding these connections,
 #'   see how the [stat][layer_stats] and [geom][layer_geoms] arguments work.
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
 #' @examples
 #' # geom_bar is designed to make it easy to create bar charts that show
 #' # counts (or sums of weights)

R/geom-bin2d.R

@@ -17,14 +17,11 @@ GeomBin2d <- ggproto("GeomBin2d", GeomTile)
 #' @aesthetics GeomBin2d
 #'
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @param geom,stat Use to override the default connection between
 #'   `geom_bin_2d()` and `stat_bin_2d()`. For more information about overriding
 #'   these connections, see how the [stat][layer_stats] and [geom][layer_geoms]
 #'   arguments work.
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
 #' @seealso [stat_bin_hex()] for hexagonal binning
 #' @examples
 #' d <- ggplot(diamonds, aes(x, y)) + xlim(4, 10) + ylim(4, 10)

R/geom-blank.R

@@ -5,8 +5,7 @@
 #' more details.
 #'
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @examples
 #' ggplot(mtcars, aes(wt, mpg))
 #' # Nothing to see here!

R/geom-boxplot.R

@@ -4,7 +4,7 @@
 #' It visualises five summary statistics (the median, two hinges
 #' and two whiskers), and all "outlying" points individually.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @section Summary statistics:
 #' The lower and upper hinges correspond to the first and third quartiles
@@ -29,8 +29,7 @@
 #' @seealso [geom_quantile()] for continuous `x`,
 #'   [geom_violin()] for a richer display of the distribution, and
 #'   [geom_jitter()] for a useful technique for small data.
-#' @inheritParams layer
-#' @inheritParams geom_bar
+#' @inheritParams shared_layer_parameters
 #' @param geom,stat Use to override the default connection between
 #'   `geom_boxplot()` and `stat_boxplot()`. For more information about
 #'   overriding these connections, see how the [stat][layer_stats] and

R/geom-contour.R

@@ -36,9 +36,7 @@ GeomContourFilled <- ggproto("GeomContourFilled", GeomPolygon)
 #'
 #' @aesthetics GeomContour
 #' @aesthetics GeomContourFilled
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @inheritParams geom_path
+#' @inheritParams shared_layer_parameters
 #' @param binwidth The width of the contour bins. Overridden by `bins`.
 #' @param bins Number of contour bins. Overridden by `breaks`.
 #' @param breaks One of:

R/geom-count.R

@@ -13,8 +13,7 @@ NULL
 #'   these connections, see how the [stat][layer_stats] and [geom][layer_geoms]
 #'   arguments work.
 #' @seealso For continuous `x` and `y`, use [geom_bin_2d()].
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @export
 #' @examples
 #' ggplot(mpg, aes(cty, hwy)) +

R/geom-density.R

@@ -21,13 +21,12 @@ GeomDensity <- ggproto(
 #' the histogram. This is a useful alternative to the histogram for continuous
 #' data that comes from an underlying smooth distribution.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #' @aesthetics GeomDensity
 #' @seealso See [geom_histogram()], [geom_freqpoly()] for
 #'   other methods of displaying continuous distribution.
 #'   See [geom_violin()] for a compact density display.
-#' @inheritParams layer
-#' @inheritParams geom_bar
+#' @inheritParams shared_layer_parameters
 #' @inheritParams geom_ribbon
 #' @param geom,stat Use to override the default connection between
 #'   `geom_density()` and `stat_density()`. For more information about