Centralise documentation for common layer arguments

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/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

R/geom-density2d.R

@@ -15,9 +15,7 @@
 #'   `geom_density_2d()` and `stat_density_2d()`. For more information at
 #'   overriding these connections, see how the [stat][layer_stats] and
 #'   [geom][layer_geoms] arguments work.
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @inheritParams geom_path
+#' @inheritParams shared_layer_parameters
 #' @param contour_var Character string identifying the variable to contour
 #'   by. Can be one of `"density"`, `"ndensity"`, or `"count"`. See the section
 #'   on computed variables for details.

R/geom-dotplot.R

@@ -29,8 +29,7 @@
 #'   ndensity = 'density, scaled to maximum of 1, if method is `"histodot"`.'
 #' )
 #'
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @param stackdir which direction to stack the dots. "up" (default),
 #'   "down", "center", "centerwhole" (centered, but with dots aligned)
 #' @param stackratio how close to stack the dots. Default is 1, where dots

R/geom-function.R

@@ -30,8 +30,7 @@ GeomFunction <- ggproto("GeomFunction", GeomPath,
 #'
 #' @aesthetics GeomFunction
 #' @param data Ignored by `stat_function()`, do not use.
-#' @inheritParams layer
-#' @inheritParams geom_path
+#' @inheritParams shared_layer_parameters
 #' @examples
 #'
 #' # geom_function() is useful for overlaying functions

R/geom-hex.R

@@ -80,11 +80,7 @@ GeomHex <- ggproto("GeomHex", Geom,
 #'   `stat_bin_hex()`. For more information about overriding these connections,
 #'   see how the [stat][layer_stats] and [geom][layer_geoms] arguments work.
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
-#' @param linemitre Line mitre limit (number greater than 1).
+#' @inheritParams shared_layer_parameters
 #' @export
 #' @examples
 #' d <- ggplot(diamonds, aes(carat, price))

R/geom-histogram.R

@@ -27,15 +27,14 @@
 #' `scale_x_binned()` with [geom_bar()]. This method by default plots tick marks
 #' in between each bar.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @section Aesthetics:
 #' `geom_histogram()` uses the same aesthetics as [geom_bar()];
 #' `geom_freqpoly()` uses the same aesthetics as [geom_line()].
 #'
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_bar
+#' @inheritParams shared_layer_parameters
 #' @param geom,stat Use to override the default connection between
 #'   `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`. For more information
 #'   at overriding these connections, see how the [stat][layer_stats] and

R/geom-jitter.R

@@ -6,8 +6,7 @@
 #' overplotting caused by discreteness in smaller datasets.
 #'
 #' @aesthetics GeomPoint
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @inheritParams position_jitter
 #' @seealso
 #'  [geom_point()] for regular, unjittered points,

R/geom-linerange.R

@@ -42,7 +42,7 @@ GeomLinerange <- ggproto(
 #' Various ways of representing a vertical interval defined by `x`,
 #' `ymin` and `ymax`. Each case draws a single graphical object.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @aesthetics GeomLinerange
 #' Note that `geom_pointrange()` also understands `size` for the size of the points.
@@ -53,8 +53,7 @@ GeomLinerange <- ggproto(
 #'  [stat_summary()] for examples of these guys in use,
 #'  [geom_smooth()] for continuous analogue
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_bar
+#' @inheritParams shared_layer_parameters
 #' @examples
 #' # Create a simple example dataset
 #' df <- data.frame(

R/geom-map.R

@@ -15,8 +15,7 @@ NULL
 #'   typically be created using [fortify()] on a spatial object.
 #'   It must contain columns `x` or `long`, `y` or
 #'   `lat`, and `region` or `id`.
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @examples
 #' # First, a made-up example containing a few polygons, to explain
 #' # how `geom_map()` works. It requires two data frames:

R/geom-path.R

@@ -178,17 +178,10 @@ GeomStep <- ggproto(
 #' An alternative parameterisation is [geom_segment()], where each line
 #' corresponds to a single case which provides the start and end coordinates.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @aesthetics GeomPath
-#' @inheritParams layer
-#' @inheritParams geom_bar
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
-#' @param linemitre Line mitre limit (number greater than 1).
-#' @param arrow Arrow specification, as created by [grid::arrow()].
-#' @param arrow.fill fill colour to use for the arrow head (if closed). `NULL`
-#'        means use `colour` aesthetic.
+#' @inheritParams shared_layer_parameters
 #' @seealso
 #'  [geom_polygon()]: Filled paths (polygons);
 #'  [geom_segment()]: Line segments

R/geom-point.R

@@ -67,34 +67,7 @@ GeomPoint <- ggproto(
 #'
 #' @aesthetics GeomPoint
 #' The `fill` aesthetic only applies to shapes 21-25.
-#' @inheritParams layer
-#' @param na.rm If `FALSE`, the default, missing values are removed with
-#'   a warning. If `TRUE`, missing values are silently removed.
-#' @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.
+#' @inheritParams shared_layer_parameters
 #'
 #' @export
 #' @examples

R/geom-polygon.R

@@ -105,11 +105,7 @@ GeomPolygon <- ggproto("GeomPolygon", Geom,
 #'  [geom_path()] for an unfilled polygon,
 #'  [geom_ribbon()] for a polygon anchored on the x-axis
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
-#' @param linemitre Line mitre limit (number greater than 1).
+#' @inheritParams shared_layer_parameters
 #' @param rule Either `"evenodd"` or `"winding"`. If polygons with holes are
 #' being drawn (using the `subgroup` aesthetic) this argument defines how the
 #' hole coordinates are interpreted. See the examples in [grid::pathGrob()] for

R/geom-quantile.R

@@ -18,9 +18,7 @@ GeomQuantile <- ggproto(
 #'
 #' @aesthetics GeomQuantile
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @inheritParams geom_path
+#' @inheritParams shared_layer_parameters
 #' @param method.args List of additional arguments passed on to the modelling
 #'   function defined by `method`.
 #' @param geom,stat Use to override the default connection between

R/geom-ribbon.R

@@ -241,16 +241,14 @@ GeomArea <- ggproto("GeomArea", GeomRibbon,
 #' of x-coordinates. To turn off this interpolation, `stat = "identity"` can
 #' be used instead.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @aesthetics GeomRibbon
 #' @seealso
 #'   [geom_bar()] for discrete intervals (bars),
 #'   [geom_linerange()] for discrete intervals (lines),
 #'   [geom_polygon()] for general polygons
-#' @inheritParams layer
-#' @inheritParams geom_bar
-#' @param linemitre Line mitre limit (number greater than 1).
+#' @inheritParams shared_layer_parameters
 #' @param outline.type Type of the outline of the area; `"both"` draws both the
 #'   upper and lower lines, `"upper"`/`"lower"` draws the respective lines only.
 #'   `"full"` draws a closed polygon around the area.

R/geom-rug.R

@@ -133,14 +133,12 @@ GeomRug <- ggproto("GeomRug", Geom,
 #' any data points under the default settings.
 #'
 #' @aesthetics GeomRug
-#' @inheritParams layer
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 #' @param sides A string that controls which sides of the plot the rugs appear on.
 #'   It can be set to a string containing any of `"trbl"`, for top, right,
 #'   bottom, and left.
 #' @param outside logical that controls whether to move the rug tassels outside of the plot area. Default is off (FALSE). You will also need to use `coord_cartesian(clip = "off")`. When set to TRUE, also consider changing the sides argument to "tr". See examples.
 #' @param length A [grid::unit()] object that sets the length of the rug lines. Use scale expansion to avoid overplotting of data.
-#' @param lineend Line end style (round, butt, square).
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(wt, mpg)) +

R/geom-segment.R

@@ -65,13 +65,7 @@ GeomSegment <- ggproto(
 #' need to connect points across multiple cases.
 #'
 #' @aesthetics GeomSegment
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @param arrow specification for arrow heads, as created by [grid::arrow()].
-#' @param arrow.fill fill colour to use for the arrow head (if closed). `NULL`
-#'        means use `colour` aesthetic.
-#' @param lineend Line end style (round, butt, square).
-#' @param linejoin Line join style (round, mitre, bevel).
+#' @inheritParams shared_layer_parameters
 #' @seealso [geom_path()] and [geom_line()] for multi-
 #'   segment lines and paths.
 #' @seealso [geom_spoke()] for a segment parameterised by a location

R/geom-sf.R

@@ -285,7 +285,7 @@ GeomSf <- ggproto("GeomSf", Geom,
 
 #' @export
 #' @rdname ggsf
-#' @inheritParams geom_point
+#' @inheritParams shared_layer_parameters
 geom_sf <- function(mapping = aes(), data = NULL, stat = "sf",
                     position = "identity", na.rm = FALSE, show.legend = NA,
                     inherit.aes = TRUE, ...) {

R/geom-smooth.R

@@ -74,11 +74,10 @@ GeomSmooth <- ggproto(
 #' `glm()`, where the normal confidence band is constructed on the link
 #' scale and then back-transformed to the response scale.
 #'
-#' @eval rd_orientation()
+#' @inheritSection shared_layer_parameters Orientation
 #'
 #' @aesthetics GeomSmooth
-#' @inheritParams layer
-#' @inheritParams geom_bar
+#' @inheritParams shared_layer_parameters
 #' @param geom,stat Use to override the default connection between
 #'   `geom_smooth()` and `stat_smooth()`. For more information about overriding
 #'   these connections, see how the [stat][layer_stats] and [geom][layer_geoms]

R/geom-spoke.R

@@ -23,8 +23,7 @@ GeomSpoke <- ggproto(
 #' The angles start from east and increase counterclockwise.
 #'
 #' @aesthetics GeomSpoke
-#' @inheritParams layer
-#' @inheritParams geom_segment
+#' @inheritParams shared_layer_parameters
 #' @export
 #' @examples
 #' df <- expand.grid(x = 1:10, y=1:10)