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.