New roxygen tag: @aesthetics (#6437)

* implement `@aesthetics` roxy tag

* Use new tag

* redocument

* add news bullet

* add roxygen2 to Suggest

* omit `ggplot2::` link prefix in ggplot2, but not extensions

Author: teunbrand

DESCRIPTION

@@ -63,6 +63,7 @@ Suggests:
     ragg (>= 1.2.6),
     RColorBrewer,
     rmarkdown,
+    roxygen2,
     rpart,
     sf (>= 0.7-3),
     svglite (>= 2.1.2),

NAMESPACE

@@ -28,6 +28,7 @@ S3method(element_grob,element_rect)
 S3method(element_grob,element_text)
 S3method(format,ggproto)
 S3method(format,ggproto_method)
+S3method(format,rd_section_aesthetics)
 S3method(fortify,"NULL")
 S3method(fortify,"function")
 S3method(fortify,Line)

NEWS.md

@@ -1,5 +1,7 @@
 # ggplot2 (development version)
 
+* New roxygen tag `@aesthetics` that takes a Geom, Stat or Position class and
+  generates an 'Aesthetics' section.
 * `annotation_borders()` replaces the now-deprecated `borders()` 
   (@teunbrand, #6392)
 * New `make_constructor()` function that builds a standard constructor for

R/geom-bar.R

@@ -68,9 +68,9 @@ GeomBar <- ggproto(
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "bar")
-#' @eval rd_aesthetics("geom", "col")
-#' @eval rd_aesthetics("stat", "count")
+#' @aesthetics GeomBar
+#' @aesthetics GeomCol
+#' @aesthetics StatCount
 #' @seealso
 #'   [geom_histogram()] for continuous data,
 #'   [position_dodge()] and [position_dodge2()] for creating side-by-side

R/geom-bin2d.R

@@ -14,7 +14,7 @@ GeomBin2d <- ggproto("GeomBin2d", GeomTile)
 #' rectangle's fill. This is a useful alternative to [geom_point()]
 #' in the presence of overplotting.
 #'
-#' @eval rd_aesthetics("stat", "bin_2d")
+#' @aesthetics GeomBin2d
 #'
 #' @export
 #' @inheritParams layer

R/geom-boxplot.R

@@ -24,7 +24,7 @@
 #' This gives a roughly 95% confidence interval for comparing medians.
 #' See McGill et al. (1978) for more details.
 #'
-#' @eval rd_aesthetics("geom", "boxplot")
+#' @aesthetics GeomBoxplot
 #'
 #' @seealso [geom_quantile()] for continuous `x`,
 #'   [geom_violin()] for a richer display of the distribution, and

R/geom-contour.R

@@ -28,8 +28,8 @@ GeomContourFilled <- ggproto("GeomContourFilled", GeomPolygon)
 #' data, you'll need to first interpolate on to a grid before visualising,
 #' using `interp::interp()`, `akima::bilinear()`, or similar.
 #'
-#' @eval rd_aesthetics("geom", "contour")
-#' @eval rd_aesthetics("geom", "contour_filled")
+#' @aesthetics GeomContour
+#' @aesthetics GeomContourFilled
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @inheritParams geom_path

R/geom-count.R

@@ -7,7 +7,7 @@ NULL
 #' observations at each location, then maps the count to point area. It
 #' useful when you have discrete data and overplotting.
 #'
-#' @eval rd_aesthetics("geom", "point")
+#' @aesthetics GeomPoint
 #' @param geom,stat Use to override the default connection between
 #'   `geom_count()` and `stat_sum()`. For more information about overriding
 #'   these connections, see how the [stat][layer_stats] and [geom][layer_geoms]

R/geom-density.R

@@ -22,8 +22,7 @@ GeomDensity <- ggproto(
 #' data that comes from an underlying smooth distribution.
 #'
 #' @eval rd_orientation()
-#'
-#' @eval rd_aesthetics("geom", "density")
+#' @aesthetics GeomDensity
 #' @seealso See [geom_histogram()], [geom_freqpoly()] for
 #'   other methods of displaying continuous distribution.
 #'   See [geom_violin()] for a compact density display.

R/geom-density2d.R

@@ -6,8 +6,8 @@
 #' draws contour lines, and `geom_density_2d_filled()` draws filled contour
 #' bands.
 #'
-#' @eval rd_aesthetics("geom", "density_2d")
-#' @eval rd_aesthetics("geom", "density_2d_filled")
+#' @aesthetics GeomDensity2d
+#' @aesthetics GeomDensity2dFilled
 #' @seealso [geom_contour()], [geom_contour_filled()] for information about
 #'  how contours are drawn; [geom_bin_2d()] for another way of dealing with
 #'  overplotting.

R/geom-dotplot.R

@@ -16,7 +16,7 @@
 #' hide the y axis, as in one of the examples, or manually scale it
 #' to match the number of dots.
 #'
-#' @eval rd_aesthetics("geom", "dotplot")
+#' @aesthetics GeomDotplot
 #' @eval rd_computed_vars(
 #'   x = 'center of each bin, if `binaxis` is `"x"`.',
 #'   y = 'center of each bin, if `binaxis` is `"x"`.',

R/geom-function.R

@@ -28,7 +28,7 @@ GeomFunction <- ggproto("GeomFunction", GeomPath,
 #' with a grid of evenly spaced values along the x axis, and the results are
 #' drawn (by default) with a line.
 #'
-#' @eval rd_aesthetics("geom", "function")
+#' @aesthetics GeomFunction
 #' @param data Ignored by `stat_function()`, do not use.
 #' @inheritParams layer
 #' @inheritParams geom_path

R/geom-hex.R

@@ -73,8 +73,8 @@ GeomHex <- ggproto("GeomHex", Geom,
 #' fill.  Hexagon bins avoid the visual artefacts sometimes generated by
 #' the very regular alignment of [geom_bin_2d()].
 #'
-#' @eval rd_aesthetics("geom", "hex")
-#' @eval rd_aesthetics("stat", "binhex")
+#' @aesthetics GeomHex
+#' @aesthetics StatBinhex
 #' @seealso [stat_bin_2d()] for rectangular binning
 #' @param geom,stat Override the default connection between `geom_hex()` and
 #'   `stat_bin_hex()`. For more information about overriding these connections,

R/geom-jitter.R

@@ -5,7 +5,7 @@
 #' variation to the location of each point, and is a useful way of handling
 #' overplotting caused by discreteness in smaller datasets.
 #'
-#' @eval rd_aesthetics("geom", "point")
+#' @aesthetics GeomPoint
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @inheritParams position_jitter

R/geom-linerange.R

@@ -44,7 +44,8 @@ GeomLinerange <- ggproto(
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "linerange", "Note that `geom_pointrange()` also understands `size` for the size of the points.")
+#' @aesthetics GeomLinerange
+#' Note that `geom_pointrange()` also understands `size` for the size of the points.
 #' @param fatten `r lifecycle::badge("deprecated")`  A multiplicative factor
 #'   used to increase the size of the middle bar in `geom_crossbar()` and the
 #'   middle point in `geom_pointrange()`.

R/geom-map.R

@@ -9,7 +9,7 @@ NULL
 #' it can be used in conjunction with `geom_sf()` layers and/or
 #' [`coord_sf()`] (see examples).
 #'
-#' @eval rd_aesthetics("geom", "map")
+#' @aesthetics GeomMap
 #' @export
 #' @param map Data frame that contains the map coordinates.  This will
 #'   typically be created using [fortify()] on a spatial object.

R/geom-path.R

@@ -180,7 +180,7 @@ GeomStep <- ggproto(
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "path")
+#' @aesthetics GeomPath
 #' @inheritParams layer
 #' @inheritParams geom_bar
 #' @param lineend Line end style (round, butt, square).

R/geom-point.R

@@ -65,7 +65,8 @@ GeomPoint <- ggproto(
 #' `geom_point(alpha = 0.05)`) or very small (e.g.
 #' `geom_point(shape = ".")`).
 #'
-#' @eval rd_aesthetics("geom", "point", "The `fill` aesthetic only applies to shapes 21-25.")
+#' @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.

R/geom-polygon.R

@@ -103,7 +103,7 @@ GeomPolygon <- ggproto("GeomPolygon", Geom,
 #' differentiates the outer ring points from those describing holes in the
 #' polygon.
 #'
-#' @eval rd_aesthetics("geom", "polygon")
+#' @aesthetics GeomPolygon
 #' @seealso
 #'  [geom_path()] for an unfilled polygon,
 #'  [geom_ribbon()] for a polygon anchored on the x-axis

R/geom-quantile.R

@@ -16,7 +16,7 @@ GeomQuantile <- ggproto(
 #' This fits a quantile regression to the data and draws the fitted quantiles
 #' with lines. This is as a continuous analogue to [geom_boxplot()].
 #'
-#' @eval rd_aesthetics("geom", "quantile")
+#' @aesthetics GeomQuantile
 #' @export
 #' @inheritParams layer
 #' @inheritParams geom_point

R/geom-ribbon.R

@@ -238,7 +238,7 @@ GeomArea <- ggproto("GeomArea", GeomRibbon,
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "ribbon")
+#' @aesthetics GeomRibbon
 #' @seealso
 #'   [geom_bar()] for discrete intervals (bars),
 #'   [geom_linerange()] for discrete intervals (lines),

R/geom-rug.R

@@ -132,7 +132,7 @@ GeomRug <- ggproto("GeomRug", Geom,
 #' variables is 5% at both ends of the scale, the rug will not overlap with
 #' any data points under the default settings.
 #'
-#' @eval rd_aesthetics("geom", "rug")
+#' @aesthetics GeomRug
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param sides A string that controls which sides of the plot the rugs appear on.

R/geom-segment.R

@@ -64,7 +64,7 @@ GeomSegment <- ggproto(
 #' Both geoms draw a single segment/curve per case. See `geom_path()` if you
 #' need to connect points across multiple cases.
 #'
-#' @eval rd_aesthetics("geom", "segment")
+#' @aesthetics GeomSegment
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param arrow specification for arrow heads, as created by [grid::arrow()].

R/geom-smooth.R

@@ -76,7 +76,7 @@ GeomSmooth <- ggproto(
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "smooth")
+#' @aesthetics GeomSmooth
 #' @inheritParams layer
 #' @inheritParams geom_bar
 #' @param geom,stat Use to override the default connection between

R/geom-spoke.R

@@ -22,7 +22,7 @@ GeomSpoke <- ggproto(
 #' useful when you have variables that describe direction and distance.
 #' The angles start from east and increase counterclockwise.
 #'
-#' @eval rd_aesthetics("geom", "spoke")
+#' @aesthetics GeomSpoke
 #' @inheritParams layer
 #' @inheritParams geom_segment
 #' @export

R/geom-text.R

@@ -75,7 +75,7 @@ GeomText <- ggproto(
 #' \href{https://cran.r-project.org/package=ggrepel}{ggrepel}
 #' package.
 #'
-#' @eval rd_aesthetics("geom", "text")
+#' @aesthetics GeomText
 #' @section `geom_label()`:
 #' Currently `geom_label()` does not support the `check_overlap` argument. Also,
 #' it is considerably slower than `geom_text()`. The `fill` aesthetic controls

R/geom-tile.R

@@ -54,11 +54,9 @@ GeomTile <- ggproto(
 #' `geom_raster()` is a high performance special case for when all the tiles
 #' are the same size, and no pattern fills are applied.
 #'
-#' @eval rd_aesthetics(
-#'   "geom", "rect",
-#'   "`geom_tile()` understands only the `x`/`width` and `y`/`height` combinations.
-#'   Note that `geom_raster()` ignores `colour`."
-#' )
+#' @aesthetics GeomRect
+#' `geom_tile()` understands only the `x`/`width` and `y`/`height` combinations.
+#' Note that `geom_raster()` ignores `colour`.
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @inheritParams geom_segment

R/geom-violin.R

@@ -7,7 +7,7 @@
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("geom", "violin")
+#' @aesthetics GeomViolin
 #' @inheritParams layer
 #' @inheritParams geom_bar
 #' @param trim If `TRUE` (default), trim the tails of the violins

R/position-dodge.R

@@ -19,7 +19,7 @@
 #' @param reverse If `TRUE`, will reverse the default stacking order.
 #'   This is useful if you're rotating both the plot and legend.
 #' @family position adjustments
-#' @eval rd_aesthetics("position", "dodge")
+#' @aesthetics PositionDodge
 #'
 #' @export
 #' @examples

R/position-nudge.R

@@ -8,7 +8,7 @@
 #' @family position adjustments
 #' @param x,y Amount of vertical and horizontal distance to move.
 #' @export
-#' @eval rd_aesthetics("position", "nudge")
+#' @aesthetics PositionNudge
 #' @examples
 #' df <- data.frame(
 #'   x = c(1,3,2,5),

R/stat-connect.R

@@ -119,7 +119,7 @@ StatConnect <- ggproto(
 #'    at location (0, 0) and point B at location (1, 1). At least one of these
 #'    two points is expected to be included in the coordinates.
 #'
-#' @eval rd_aesthetics("stat", "connect")
+#' @aesthetics StatConnect
 #' @export
 #'
 #' @examples

R/stat-contour.R

@@ -87,8 +87,8 @@ StatContourFilled <- ggproto(
 #' @inheritParams stat_identity
 #' @inheritParams geom_contour
 #' @export
-#' @eval rd_aesthetics("stat", "contour")
-#' @eval rd_aesthetics("stat", "contour_filled")
+#' @aesthetics StatContour
+#' @aesthetics StatContourFilled
 #' @eval rd_computed_vars(
 #'   .details = "The computed variables differ somewhat for contour lines
 #'   (computed by `stat_contour()`) and contour bands (filled contours,

R/stat-ecdf.R

@@ -73,7 +73,7 @@ StatEcdf <- ggproto(
 #'   of points to interpolate with.
 #' @param pad If `TRUE`, pad the ecdf with additional points (-Inf, 0)
 #'   and (Inf, 1)
-#' @eval rd_aesthetics("stat", "ecdf")
+#' @aesthetics StatEcdf
 #' @eval rd_computed_vars(
 #'   ecdf = "Cumulative density corresponding to `x`.",
 #'   y    = "`r lifecycle::badge('superseded')` For backward compatibility."

R/stat-ellipse.R

@@ -45,7 +45,7 @@ StatEllipse <- ggproto(
 #' @param segments The number of segments to be used in drawing the ellipse.
 #' @inheritParams layer
 #' @inheritParams geom_point
-#' @eval rd_aesthetics("stat", "ellipse")
+#' @aesthetics StatEllipse
 #' @export
 #' @examples
 #' ggplot(faithful, aes(waiting, eruptions)) +

R/stat-manual.R

@@ -28,7 +28,7 @@ StatManual <- ggproto(
 #'   the data unchanged.
 #' @param args A list of arguments to pass to the function given in `fun`.
 #'
-#' @eval rd_aesthetics("stat", "manual")
+#' @aesthetics StatManual
 #' @section Aesthetics:
 #' Input aesthetics are determined by the `fun` argument. Output aesthetics must
 #' include those required by `geom`. Any aesthetic that is constant within a

R/stat-qq.R

@@ -34,8 +34,8 @@ StatQq <- ggproto(
 #' `stat_qq_line()` compute the slope and intercept of the line connecting the
 #' points at specified quartiles of the theoretical and sample distributions.
 #'
-#' @eval rd_aesthetics("stat", "qq")
-#' @eval rd_aesthetics("stat", "qq_line")
+#' @aesthetics StatQq
+#' @aesthetics StatQqLine
 #' @param distribution Distribution function to use, if x not specified
 #' @param dparams Additional parameters passed on to `distribution`
 #'   function.

R/stat-summary.R

@@ -7,7 +7,7 @@
 #'
 #' @eval rd_orientation()
 #'
-#' @eval rd_aesthetics("stat", "summary")
+#' @aesthetics StatSummary
 #' @seealso [geom_errorbar()], [geom_pointrange()],
 #'  [geom_linerange()], [geom_crossbar()] for geoms to
 #'  display summarised data

R/stat-unique.R

@@ -9,7 +9,7 @@ StatUnique <- ggproto(
 
 #' Remove duplicates
 #'
-#' @eval rd_aesthetics("stat", "unique")
+#' @aesthetics StatUnique
 #' @export
 #' @inheritParams layer
 #' @inheritParams geom_point