Minor Documentation Fixes (#2768)

* A second round of minor doc fixes throughout stack

* Clarify geom_boxplot examples

Closes #2793

Author: Dana Paige Seidel

R/facet-grid-.r

@@ -3,7 +3,7 @@ NULL
 
 #' Lay out panels in a grid
 #'
-#' `facet_grid` forms a matrix of panels defined by row and column
+#' `facet_grid()` forms a matrix of panels defined by row and column
 #' faceting variables. It is most useful when you have two discrete
 #' variables, and all combinations of the variables exist in the data.
 #'

R/geom-abline.r

@@ -25,9 +25,9 @@ NULL
 #' `size`. They also each have aesthetics that control the position of
 #' the line:
 #'
-#'   - `geom_vline`: `xintercept`
-#'   - `geom_hline`: `yintercept`
-#'   - `geom_abline`: `slope` and `intercept`
+#'   - `geom_vline()`: `xintercept`
+#'   - `geom_hline()`: `yintercept`
+#'   - `geom_abline()`: `slope` and `intercept`
 #'
 #' @seealso See [geom_segment()] for a more general approach to
 #'   adding straight line segments to a plot.

R/geom-boxplot.r

@@ -7,9 +7,9 @@
 #' @section Summary statistics:
 #' The lower and upper hinges correspond to the first and third quartiles
 #' (the 25th and 75th percentiles). This differs slightly from the method used
-#' by the `boxplot` function, and may be apparent with small samples.
+#' by the [boxplot()] function, and may be apparent with small samples.
 #' See [boxplot.stats()] for for more information on how hinge
-#' positions are calculated for `boxplot`.
+#' positions are calculated for [boxplot()].
 #'
 #' The upper whisker extends from the hinge to the largest value no further than
 #' 1.5 * IQR from the hinge (where IQR is the inter-quartile range, or distance
@@ -24,7 +24,7 @@
 #'
 #' @eval rd_aesthetics("geom", "boxplot")
 #'
-#' @seealso [geom_quantile()] for continuous x,
+#' @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
@@ -60,7 +60,6 @@
 #' @examples
 #' p <- ggplot(mpg, aes(class, hwy))
 #' p + geom_boxplot()
-#' p + geom_boxplot() + geom_jitter(width = 0.2)
 #' p + geom_boxplot() + coord_flip()
 #'
 #' p + geom_boxplot(notch = TRUE)
@@ -69,6 +68,8 @@
 #' # By default, outlier points match the colour of the box. Use
 #' # outlier.colour to override
 #' p + geom_boxplot(outlier.colour = "red", outlier.shape = 1)
+#' # Remove outliers when overlaying boxplot with original data points
+#' p + geom_boxplot(outlier.shape = NA) + geom_jitter(width = 0.2)
 #'
 #' # Boxplots are automatically dodged when any aesthetic is a factor
 #' p + geom_boxplot(aes(colour = drv))
@@ -79,6 +80,7 @@
 #'   geom_boxplot()
 #' ggplot(diamonds, aes(carat, price)) +
 #'   geom_boxplot(aes(group = cut_width(carat, 0.25)))
+#' # Adjust the transparency of outliers using outlier.alpha
 #' ggplot(diamonds, aes(carat, price)) +
 #'   geom_boxplot(aes(group = cut_width(carat, 0.25)), outlier.alpha = 0.1)
 #'

R/geom-histogram.r

@@ -2,28 +2,28 @@
 #'
 #' Visualise the distribution of a single continuous variable by dividing
 #' the x axis into bins and counting the number of observations in each bin.
-#' Histograms (`geom_histogram`) display the count with bars; frequency
-#' polygons (`geom_freqpoly`) display the counts with lines. Frequency
+#' Histograms (`geom_histogram()`) display the counts with bars; frequency
+#' polygons (`geom_freqpoly()`) display the counts with lines. Frequency
 #' polygons are more suitable when you want to compare the distribution
 #' across the levels of a categorical variable.
 #'
-#' `stat_bin` is suitable only for continuous x data. If your x data is
+#' `stat_bin()` is suitable only for continuous x data. If your x data is
 #' discrete, you probably want to use [stat_count()].
 #'
-#' By default, the underlying computation (`stat_bin`) uses 30 bins;
+#' By default, the underlying computation (`stat_bin()`) uses 30 bins;
 #' this is not a good default, but the idea is to get you experimenting with
 #' different bin widths. You may need to look at a few to uncover the full
 #' story behind your data.
 #'
 #' @section Aesthetics:
-#' `geom_histogram` uses the same aesthetics as [geom_bar()];
-#' `geom_freqpoly` uses the same aesthetics as [geom_line()].
+#' `geom_histogram()` uses the same aesthetics as [geom_bar()];
+#' `geom_freqpoly()` uses the same aesthetics as [geom_line()].
 #'
 #' @export
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param geom,stat Use to override the default connection between
-#'   `geom_histogram`/`geom_freqpoly` and `stat_bin`.
+#'   `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`.
 #' @examples
 #' ggplot(diamonds, aes(carat)) +
 #'   geom_histogram()

R/geom-point.r

@@ -5,11 +5,8 @@
 #' It can be used to compare one continuous and one categorical variable, or
 #' two categorical variables, but a variation like [geom_jitter()],
 #' [geom_count()], or [geom_bin2d()] is usually more
-#' appropriate.
-#'
-#' The \emph{bubblechart} is a scatterplot with a third variable mapped to
-#' the size of points. There are no special names for scatterplots where
-#' another variable is mapped to point shape or colour, however.
+#' appropriate. A _bubblechart_ is a scatterplot with a third variable
+#' mapped to the size of points.
 #'
 #' @section Overplotting:
 #' The biggest potential problem with a scatterplot is overplotting: whenever
@@ -47,6 +44,7 @@
 #' # Add aesthetic mappings
 #' p + geom_point(aes(colour = factor(cyl)))
 #' p + geom_point(aes(shape = factor(cyl)))
+#' # A "bubblechart":
 #' p + geom_point(aes(size = qsec))
 #'
 #' # Set aesthetics to fixed value

R/geom-smooth.r

@@ -1,22 +1,22 @@
 #' Smoothed conditional means
 #'
 #' Aids the eye in seeing patterns in the presence of overplotting.
-#' `geom_smooth` and `stat_smooth` are effectively aliases: they
-#' both use the same arguments. Use `geom_smooth` unless you want to
+#' `geom_smooth()` and `stat_smooth()` are effectively aliases: they
+#' both use the same arguments. Use `stat_smooth()` if you want to
 #' display the results with a non-standard geom.
 #'
 #' Calculation is performed by the (currently undocumented)
-#' `predictdf` generic and its methods.  For most methods the standard
+#' `predictdf()` generic and its methods.  For most methods the standard
 #' error bounds are computed using the [predict()] method -- the
-#' exceptions are `loess`, which uses a t-based approximation, and
-#' `glm`, where the normal confidence interval is constructed on the link
+#' exceptions are `loess()`, which uses a t-based approximation, and
+#' `glm()`, where the normal confidence interval is constructed on the link
 #' scale and then back-transformed to the response scale.
 #'
 #' @eval rd_aesthetics("geom", "smooth")
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param geom,stat Use to override the default connection between
-#'   `geom_smooth` and `stat_smooth`.
+#'   `geom_smooth()` and `stat_smooth()`.
 #' @seealso See individual modelling functions for more details:
 #'   [lm()] for linear smooths,
 #'   [glm()] for generalised linear smooths, and

R/geom-text.r

@@ -1,6 +1,6 @@
 #' Text
 #'
-#' `geom_text` adds text directly to the plot. `geom_label` draws
+#' `geom_text()` adds text directly to the plot. `geom_label()` draws
 #' a rectangle behind the text, making it easier to read.
 #'
 #' Note that the "width" and "height" of a text element are 0, so stacking
@@ -10,16 +10,16 @@
 #' space they occupy on the plot is not constant in data units: when you
 #' resize a plot, labels stay the same size, but the size of the axes changes.
 #'
-#' `geom_text` and `geom_label` both add a label for each row in the
+#' `geom_text()` and `geom_label()` add labels for each row in the
 #' data, even if coordinates x, y are set to single values in the call
-#' to `geom_label` or `geom_text`.
+#' to `geom_label()` or `geom_text()`.
 #' To add labels at specified points use [annotate()] with
 #' `annotate(geom = "text", ...)` or `annotate(geom = "label", ...)`.
 #'
 #' @eval rd_aesthetics("geom", "text")
-#' @section `geom_label`:
-#' Currently `geom_label` does not support the `angle` aesthetic and
-#' is considerably slower than `geom_text`. The `fill` aesthetic
+#' @section `geom_label()`:
+#' Currently `geom_label()` does not support the `angle` aesthetic and
+#' is considerably slower than `geom_text()`. The `fill` aesthetic
 #' controls the background colour of the label.
 #'
 #' @section Alignment:

R/guide-legend.r

@@ -57,7 +57,6 @@
 #'   multiple guides are displayed, not the contents of the guide itself.
 #'   If 0 (default), the order is determined by a secret algorithm.
 #' @param ... ignored.
-#' @return A guide object
 #' @export
 #' @family guides
 #' @examples

R/labels.r

@@ -19,14 +19,15 @@ update_labels <- function(p, labels) {
 #' Modify axis, legend, and plot labels
 #'
 #' Good labels are critical for making your plots accessible to a wider
-#' audience. Ensure the axis and legend labels display the full variable name.
-#' Use the plot `title` and `subtitle` to explain the main findings.
-#' It's common to use the `caption` to provide information about the
-#' data source. `tag` can be used for adding identification tags.
+#' audience. Always ensure the axis and legend labels display the full
+#' variable name. Use the plot `title` and `subtitle` to explain the
+#' main findings. It's common to use the `caption` to provide information
+#' about the data source. `tag` can be used for adding identification tags
+#' to differentiate between multiple plots.
 #'
 #' You can also set axis and legend labels in the individual scales (using
-#' the first argument, the `name`). I recommend doing that if you're
-#' changing other scale options.
+#' the first argument, the `name`). If you're changing other scale options, this
+#' is recommended.
 #'
 #' @param label The text for the axis, plot title or caption below the plot.
 #' @param subtitle the text for the subtitle for the plot which will be

R/save.r

@@ -32,6 +32,7 @@
 #' ggsave("mtcars.pdf", width = 4, height = 4)
 #' ggsave("mtcars.pdf", width = 20, height = 20, units = "cm")
 #'
+#' # delete files with base::unlink()
 #' unlink("mtcars.pdf")
 #' unlink("mtcars.png")
 #'

R/scale-.r

@@ -502,7 +502,7 @@ ScaleDiscrete <- ggproto("ScaleDiscrete", Scale,
 #' @param palette A palette function that when called with a single integer
 #'   argument (the number of levels in the scale) returns the values that
 #'   they should take
-#' @param name The name of the scale. Used as axis or legend title. If
+#' @param name The name of the scale. Used as the axis or legend title. If
 #'   `waiver()`, the default, the name of the scale is taken from the first
 #'   mapping used for that aesthetic. If `NULL`, the legend title will be
 #'   omitted.

R/scale-continuous.r

@@ -1,16 +1,16 @@
 #' Position scales for continuous data (x & y)
 #'
-#' `scale_x_continuous` and `scale_y_continuous` are the default
+#' `scale_x_continuous()` and `scale_y_continuous()` are the default
 #' scales for continuous x and y aesthetics. There are three variants
 #' that set the `trans` argument for commonly used transformations:
-#' `scale_*_log10`, `scale_*_sqrt` and `scale_*_reverse`.
+#' `scale_*_log10()`, `scale_*_sqrt()` and `scale_*_reverse()`.
 #'
 #' For simple manipulation of labels and limits, you may wish to use
 #' [labs()] and [lims()] instead.
 #'
 #' @inheritParams continuous_scale
 #' @family position scales
-#' @param ... Other arguments passed on to `scale_(x|y)_continuous`
+#' @param ... Other arguments passed on to `scale_(x|y)_continuous()`
 #' @examples
 #' p1 <- ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point()

R/scale-gradient.r

@@ -15,7 +15,7 @@
 #' @param low,high Colours for low and high ends of the gradient.
 #' @param guide Type of legend. Use `"colourbar"` for continuous
 #'   colour bar, or `"legend"` for discrete colour legend.
-#' @inheritDotParams continuous_scale -na.value -guide
+#' @inheritDotParams continuous_scale -na.value -guide -aesthetics
 #' @seealso [scales::seq_gradient_pal()] for details on underlying
 #'   palette
 #' @family colour scales

R/stat-bin.r

@@ -8,17 +8,15 @@
 #'   The bin width of a date variable is the number of days in each time; the
 #'   bin width of a time variable is the number of seconds.
 #' @param bins Number of bins. Overridden by `binwidth`. Defaults to 30.
-#' @param center The center of one of the bins.  Note that if center is above or
-#'   below the range of the data, things will be shifted by an appropriate
-#'   number of `width`s. To center on integers, for example, use
-#'   `width = 1` and `center = 0`, even if `0` is outside the range
-#'   of the data.  At most one of `center` and `boundary` may be
-#'   specified.
-#' @param boundary A boundary between two bins. As with `center`, things
-#'   are shifted when `boundary` is outside the range of the data. For
-#'   example, to center on integers, use `width = 1` and \code{boundary =
-#'   0.5}, even if `0.5` is outside the range of the data.  At most one of
-#'   `center` and `boundary` may be specified.
+#' @param center,boundary bin position specifiers. Only one, `center` or
+#'   `boundary`, may be specified for a single plot. `center` specifies the
+#'   center of one of the bins. `boundary` specifies the boundary between two
+#'   bins. Note that if either is above or below the range of the data, things
+#'   will be shifted by the appropriate integer multiple of `width`.
+#'   For example, to center on integers use `width = 1` and `center = 0`, even
+#'   if `0` is outside the range of the data. Alternatively, this same alignment
+#'   can be specified with `width = 1` and `boundary = 0.5`, even if `0.5` is
+#'   outside the range of the data.
 #' @param breaks Alternatively, you can supply a numeric vector giving
 #'    the bin boundaries. Overrides `binwidth`, `bins`, `center`,
 #'    and `boundary`.
@@ -36,7 +34,7 @@
 #'
 #' @seealso [stat_count()], which counts the number of cases at each x
 #'   position, without binning. It is suitable for both discrete and continuous
-#'   x data, whereas \link{stat_bin} is suitable only for continuous x data.
+#'   x data, whereas `stat_bin()` is suitable only for continuous x data.
 #' @export
 #' @rdname geom_histogram
 stat_bin <- function(mapping = NULL, data = NULL,

R/stat-smooth.r

@@ -1,5 +1,6 @@
-#' @param method Smoothing method (function) to use, eg. `lm`, `glm`,
-#'   `gam`, `loess`, `MASS::rlm`.
+#' @param method Smoothing method (function) to use, accepts either a character vector,
+#'   e.g. `"auto"`, `"lm"`, `"glm"`, `"gam"`, `"loess"` or a function, e.g.
+#'   `MASS::rlm` or `mgcv::gam`, `base::lm`, or `base::loess`.
 #'
 #'   For `method = "auto"` the smoothing method is chosen based on the
 #'   size of the largest group (across all panels). [loess()] is
@@ -8,8 +9,8 @@
 #'   `loess` gives a better appearance, but is \eqn{O(N^{2})}{O(N^2)} in memory,
 #'   so does not work for larger datasets.
 #'
-#'   If you have fewer than 1,000 observations but want to use the same `gam`
-#'   model that `method = "auto"` would use then set
+#'   If you have fewer than 1,000 observations but want to use the same `gam()`
+#'   model that `method = "auto"` would use, then set
 #'   `method = "gam", formula = y ~ s(x, bs = "cs")`.
 #' @param formula Formula to use in smoothing function, eg. `y ~ x`,
 #'   `y ~ poly(x, 2)`, `y ~ log(x)`

R/utilities-help.r

@@ -9,7 +9,7 @@ rd_aesthetics <- function(type, name) {
   c(
     "@section Aesthetics:",
     paste0(
-      "\\code{", type, "_", name, "} ",
+      "\\code{", type, "_", name, "()} ",
       "understands the following aesthetics (required aesthetics are in bold):"
     ),
     "\\itemize{",