better docs for waived arguments

R/auto_partial.R

@@ -51,7 +51,7 @@
 #' These function families (except [point_interval()]) also support passing
 #' [waiver]s to their optional arguments: if [waiver()] is passed to any
 #' of these arguments, their default value (or the most
-#' recently-partially-applied non-`waiver` value) is used instead.
+#' recently-partially-applied non-[waiver] value) is used instead.
 #'
 #' Use the [auto_partial()] function to create new functions that support
 #' automatic partial application.
@@ -227,5 +227,46 @@ print.ggdist_partial_function = function(x, ...) {
   invisible(x)
 }
 
+
+#' A waived argument
+#'
+#' A flag indicating that the default value of an argument should be used.
+#'
+#' @details
+#' A [waiver()] is a flag passed to a function argument that indicates the
+#' function should use the default value of that argument. It is used in two
+#' cases:
+#'
+#' - \pkg{ggplot2} functions use it to distinguish between "nothing" (`NULL`)
+#'    and a default value calculated elsewhere ([waiver()]).
+#'
+#' - \pkg{ggdist} turns \pkg{ggplot2}'s convention into a standardized method of
+#'    argument-passing: any named argument with a default value in an
+#'    [automatically partially-applied function][auto_partial] can be passed
+#'    [waiver()] when calling the function. This will cause the default value
+#'    (or the most recently partially-applied value) of that argument to be used
+#'    instead.
+#'
+#'    **Note:** due to historical limitations, [waiver()] cannot currently be
+#'    used on arguments to the [point_interval()] family of functions.
+#'
+#' @seealso [auto_partial()], [ggplot2::waiver()]
+#' @examples
+#' f = auto_partial(function(x, y = "b") {
+#'   c(x = x, y = y)
+#' })
+#'
+#' f("a")
+#'
+#' # uses the default value of `y` ("b")
+#' f("a", y = waiver())
+#'
+#' # partially apply `f`
+#' g = f(y = "c")
+#' g
+#'
+#' # uses the last partially-applied value of `y` ("c")
+#' g("a", y = waiver())
+#' @importFrom ggplot2 waiver
 #' @export
-ggplot2::waiver
+waiver = ggplot2::waiver

R/bounder.R

@@ -9,7 +9,7 @@
 #'
 #' Estimate the bounds of the distribution a sample came from using the CDF of
 #' the order statistics of the sample. Use with the `bounder` argument to [density_bounded()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x numeric vector containing a sample to estimate the bounds of.
 #' @param p scalar in \eqn{[0,1]}: percentile of the order statistic distribution to use
@@ -90,7 +90,7 @@ bounder_cdf = auto_partial(name = "bounder_cdf", function(x, p = 0.01) {
 #'
 #' Estimate the bounds of the distribution a sample came from using Cooke's method.
 #' Use with the `bounder` argument to [density_bounded()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritParams bounder_cdf
 #'
@@ -158,7 +158,7 @@ bounder_cooke = auto_partial(name = "bounder_cooke", function(x) {
 #'
 #' Estimate the bounds of the distribution a sample came from using the range of the sample.
 #' Use with the `bounder` argument to [density_bounded()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritParams bounder_cdf
 #'

R/density.R

@@ -10,7 +10,7 @@
 #' Unbounded density estimator
 #'
 #' Unbounded density estimator using [stats::density()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x numeric vector containing a sample to compute a density estimate for.
 #' @param weights optional numeric vector of weights to apply to `x`.
@@ -122,7 +122,7 @@ density_unbounded = auto_partial(name = "density_unbounded", function(
 #' Bounded density estimator using the reflection method
 #'
 #' Bounded density estimator using the reflection method.
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritParams density_unbounded
 #' @param bounds length-2 vector of min and max bounds. If a bound is `NA`, then
@@ -261,7 +261,7 @@ density_bounded = auto_partial(name = "density_bounded", function(
 #' Histogram density estimator
 #'
 #' Histogram density estimator.
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x numeric vector containing a sample to compute a density estimate for.
 #' @param weights optional numeric vector of weights to apply to `x`.
@@ -413,7 +413,7 @@ plot.ggdist_density = function(x, ..., ylim = c(0, NA)) {
 #'
 #' Bandwidth estimators for densities, used in the `bandwidth` argument
 #' to density functions (e.g. [density_bounded()], [density_unbounded()]).
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritDotParams stats::bw.SJ
 #' @param x A numeric vector giving a sample.

R/geom_blur_dots.R

@@ -235,7 +235,7 @@ geom_blur_dots = make_geom(GeomBlurDots)
 #' @description
 #' Methods for constructing blurs, as used in the `blur` argument to
 #' [geom_blur_dots()] or [stat_mcse_dots()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #' @param x numeric vector of positive distances from the center of the dot
 #' (assumed to be 0) to evaluate blur function at.
 #' @param r radius of the dot that is being blurred.

R/point_interval.R

@@ -13,7 +13,9 @@ globalVariables(c("y", "ymin", "ymax"))
 #' Translates draws from distributions in a (possibly grouped) data frame into point and
 #' interval summaries (or set of point and interval summaries, if there are
 #' multiple groups in a grouped data frame).
+#' @template description-auto-partial
 #'
+#' @details
 #' If `.data` is a data frame, then `...` is a list of bare names of
 #' columns (or expressions derived from columns) of `.data`, on which
 #' the point and interval summaries are derived. Column expressions are processed

R/smooth.R

@@ -9,7 +9,7 @@
 #' Smooths `x` values using a density estimator, returning new `x` of the same
 #' length. Can be used with a dotplot (e.g. [`geom_dots`]`(smooth = ...)`) to create
 #' "density dotplots".
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x a numeric vector
 #' @param density Density estimator to use for smoothing. One of:
@@ -139,7 +139,7 @@ smooth_unbounded = auto_partial(name = "smooth_unbounded", function(
 #' dataset; `smooth_discrete()` uses a kernel density estimator and `smooth_bar()`
 #' places values in an evenly-spaced grid. Can be used with a dotplot
 #' (e.g. [`geom_dots`]`(smooth = ...)`) to create "bar dotplots".
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x a numeric vector
 #' @param width approximate width of the bars as a fraction of data [resolution()].
@@ -240,7 +240,7 @@ smooth_bar = auto_partial(name = "smooth_bar", function(x, width = 0.7, ...) {
 #' Apply no smooth to a dotplot
 #'
 #' Default smooth for dotplots: no smooth. Simply returns the input values.
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x a numeric vector
 #' @param ... ignored

R/subguide.R

@@ -3,7 +3,7 @@
 #' This is a sub-guide intended for annotating the `thickness` aesthetic
 #' in \pkg{ggdist}. It can be used with the `subguide` parameter of
 #' [geom_slabinterval()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritParams scale_thickness
 #' @param values Values used to construct the scale used for this guide.

R/subscale.R

@@ -3,7 +3,7 @@
 #' This is a sub-scale intended for adjusting the scaling of the `thickness`
 #' aesthetic at a geometry (or sub-geometry) level in \pkg{ggdist}. It can be
 #' used with the `subscale` parameter of [geom_slabinterval()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @inheritParams scale_thickness
 #' @param x a [numeric] vector to be rescaled.

R/weighted_hist.R

@@ -56,7 +56,7 @@ weighted_hist = function(
 #'
 #' Methods for determining breaks (bins) in histograms, as used in the `breaks`
 #' argument to [density_histogram()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param x A numeric vector giving a sample.
 #' @param weights A numeric vector of `length(x)` giving sample weights.
@@ -255,7 +255,7 @@ breaks_quantiles = auto_partial(name = "breaks_quantiles", function(
 #'
 #' Methods for aligning breaks (bins) in histograms, as used in the `align`
 #' argument to [density_histogram()].
-#' @template description-auto-partial
+#' @template description-auto-partial-waivable
 #'
 #' @param breaks A sorted vector of breaks (bin edges).
 #' @param at A scalar numeric giving an alignment point.

man-roxygen/description-auto-partial-waivable.R

@@ -0,0 +1,3 @@
+#' @description
+#' Supports [automatic partial function application][auto_partial] with
+#' [waived arguments][waiver].

man-roxygen/description-auto-partial.R

@@ -1,2 +1,2 @@
 #' @description
-#' Supports [automatic partial function application][automatic-partial-functions].
+#' Supports [automatic partial function application][auto_partial].