Documentation improvements (#4851)

* Update to roxygen 7.2.0

* Add docs/ to .Rbuildignore
This commit is contained in:
Hadley Wickham 2022-05-19 16:59:44 -07:00 committed by GitHub
parent d6f5bf4ac1
commit 7d05f492e6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 66 additions and 69 deletions

View File

@ -28,3 +28,4 @@ visual_test
^LICENSE\.md$
^vignettes/articles$
^CRAN-SUBMISSION$
^docs$

View File

@ -80,7 +80,7 @@ Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2
RoxygenNote: 7.2.0
Collate:
'ggproto.r'
'ggplot-global.R'

View File

@ -42,7 +42,9 @@ with \code{aes_string()} is quite clunky.
All these functions are soft-deprecated. Please use tidy evaluation idioms
instead. Regarding \code{aes_string()}, you can replace it with \code{.data} pronoun.
For example, the following code can achieve the same mapping as
\code{aes_string(x_var, y_var)}.\if{html}{\out{<div class="sourceCode r">}}\preformatted{x_var <- "foo"
\code{aes_string(x_var, y_var)}.
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x_var <- "foo"
y_var <- "bar"
aes(.data[[x_var]], .data[[y_var]])
}\if{html}{\out{</div>}}

View File

@ -10,9 +10,7 @@ coord_fixed(ratio = 1, xlim = NULL, ylim = NULL, expand = TRUE, clip = "on")
\arguments{
\item{ratio}{aspect ratio, expressed as \code{y / x}}
\item{xlim}{Limits for the x and y axes.}
\item{ylim}{Limits for the x and y axes.}
\item{xlim, ylim}{Limits for the x and y axes.}
\item{expand}{If \code{TRUE}, the default, adds a small expansion factor to
the limits to ensure that data and axes don't overlap. If \code{FALSE},

View File

@ -7,9 +7,7 @@
coord_flip(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on")
}
\arguments{
\item{xlim}{Limits for the x and y axes.}
\item{ylim}{Limits for the x and y axes.}
\item{xlim, ylim}{Limits for the x and y axes.}
\item{expand}{If \code{TRUE}, the default, adds a small expansion factor to
the limits to ensure that data and axes don't overlap. If \code{FALSE},

View File

@ -18,9 +18,7 @@ coord_trans(
\arguments{
\item{x, y}{Transformers for x and y axes or their names.}
\item{xlim}{Limits for the x and y axes.}
\item{ylim}{Limits for the x and y axes.}
\item{xlim, ylim}{Limits for the x and y axes.}
\item{limx, limy}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} use \code{xlim} and \code{ylim} instead.}

View File

@ -53,16 +53,7 @@ often aesthetics, used to set an aesthetic to a fixed value, like
\code{colour = "red"} or \code{size = 3}. They may also be parameters
to the paired geom/stat.}
\item{width}{Amount of vertical and horizontal jitter. The jitter
is added in both positive and negative directions, so the total spread
is twice the value specified here.
If omitted, defaults to 40\% of the resolution of the data: this means the
jitter values will occupy 80\% of the implied bins. Categorical data
is aligned on the integers, so a width or height of 0.5 will spread the
data so it's not possible to see the distinction between the categories.}
\item{height}{Amount of vertical and horizontal jitter. The jitter
\item{width, height}{Amount of vertical and horizontal jitter. The jitter
is added in both positive and negative directions, so the total spread
is twice the value specified here.

View File

@ -6,7 +6,7 @@
\alias{ggplot2-package}
\title{ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics}
\description{
\if{html}{\figure{logo.png}{options: align='right' alt='logo' width='120'}}
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
A system for 'declaratively' creating graphics, based on "The Grammar of Graphics". You provide the data, tell 'ggplot2' how to map variables to aesthetics, what graphical primitives to use, and it takes care of the details.
}

View File

@ -228,11 +228,7 @@ to the paired geom/stat.}
\item{parse}{If \code{TRUE}, the labels will be parsed into expressions and
displayed as described in \code{?plotmath}.}
\item{nudge_x}{Horizontal and vertical adjustment to nudge labels by.
Useful for offsetting text from points, particularly on discrete scales.
Cannot be jointly specified with \code{position}.}
\item{nudge_y}{Horizontal and vertical adjustment to nudge labels by.
\item{nudge_x, nudge_y}{Horizontal and vertical adjustment to nudge labels by.
Useful for offsetting text from points, particularly on discrete scales.
Cannot be jointly specified with \code{position}.}

View File

@ -59,11 +59,7 @@ rather than combining with them. This is most useful for helper functions
that define both data and aesthetics and shouldn't inherit behaviour from
the default plot specification, e.g. \code{\link[=borders]{borders()}}.}
\item{check.aes}{If \code{TRUE}, the default, will check that
supplied parameters and aesthetics are understood by the \code{geom} or
\code{stat}. Use \code{FALSE} to suppress the checks.}
\item{check.param}{If \code{TRUE}, the default, will check that
\item{check.aes, check.param}{If \code{TRUE}, the default, will check that
supplied parameters and aesthetics are understood by the \code{geom} or
\code{stat}. Use \code{FALSE} to suppress the checks.}

View File

@ -77,7 +77,8 @@ scale_fill_fermenter(
or \code{\link[=binned_scale]{binned_scale()}}, for \code{brewer}, \code{distiller}, and \code{fermenter} variants
respectively, to control name, limits, breaks, labels and so forth.}
\item{type}{One of seq (sequential), div (diverging) or qual (qualitative)}
\item{type}{One of "seq" (sequential), "div" (diverging) or "qual"
(qualitative)}
\item{palette}{If a string, will use that named palette. If a number, will index into
the list of palettes of appropriate \code{type}. The list of available palettes can found

View File

@ -70,14 +70,14 @@ transformation object
as output. Also accepts rlang \link[rlang:as_function]{lambda} function
notation.
}}
\item{\code{guide}}{A function used to create a guide or its name. See
\code{\link[=guides]{guides()}} for more information.}
\item{\code{expand}}{For position scales, a vector of range expansion constants used to add some
padding around the data to ensure that they are placed some distance
away from the axes. Use the convenience function \code{\link[=expansion]{expansion()}}
to generate the values for the \code{expand} argument. The defaults are to
expand the scale by 5\% on each side for continuous variables, and by
0.6 units on each side for discrete variables.}
\item{\code{guide}}{A function used to create a guide or its name. See
\code{\link[=guides]{guides()}} for more information.}
\item{\code{position}}{For position scales, The position of the axis.
\code{left} or \code{right} for y axes, \code{top} or \code{bottom} for x axes.}
\item{\code{super}}{The super class to use for the constructed scale}

View File

@ -76,14 +76,14 @@ transformation object
as output. Also accepts rlang \link[rlang:as_function]{lambda} function
notation.
}}
\item{\code{guide}}{A function used to create a guide or its name. See
\code{\link[=guides]{guides()}} for more information.}
\item{\code{expand}}{For position scales, a vector of range expansion constants used to add some
padding around the data to ensure that they are placed some distance
away from the axes. Use the convenience function \code{\link[=expansion]{expansion()}}
to generate the values for the \code{expand} argument. The defaults are to
expand the scale by 5\% on each side for continuous variables, and by
0.6 units on each side for discrete variables.}
\item{\code{guide}}{A function used to create a guide or its name. See
\code{\link[=guides]{guides()}} for more information.}
\item{\code{position}}{For position scales, The position of the axis.
\code{left} or \code{right} for y axes, \code{top} or \code{bottom} for x axes.}
\item{\code{super}}{The super class to use for the constructed scale}

View File

@ -139,12 +139,6 @@ bounds values with \code{NA}.
\item \code{\link[scales:oob]{scales::squish()}} for squishing out of bounds values into range.
\item \code{\link[scales:oob]{scales::squish_infinite()}} for squishing infinite values into range.
}}
\item{\code{expand}}{For position scales, a vector of range expansion constants used to add some
padding around the data to ensure that they are placed some distance
away from the axes. Use the convenience function \code{\link[=expansion]{expansion()}}
to generate the values for the \code{expand} argument. The defaults are to
expand the scale by 5\% on each side for continuous variables, and by
0.6 units on each side for discrete variables.}
\item{\code{trans}}{For continuous scales, the name of a transformation object
or the object itself. Built-in transformations include "asn", "atanh",
"boxcox", "date", "exp", "hms", "identity", "log", "log10", "log1p", "log2",
@ -156,14 +150,18 @@ and methods for generating breaks and labels. Transformation objects
are defined in the scales package, and are called \verb{<name>_trans} (e.g.,
\code{\link[scales:boxcox_trans]{scales::boxcox_trans()}}). You can create your own
transformation with \code{\link[scales:trans_new]{scales::trans_new()}}.}
\item{\code{expand}}{For position scales, a vector of range expansion constants used to add some
padding around the data to ensure that they are placed some distance
away from the axes. Use the convenience function \code{\link[=expansion]{expansion()}}
to generate the values for the \code{expand} argument. The defaults are to
expand the scale by 5\% on each side for continuous variables, and by
0.6 units on each side for discrete variables.}
\item{\code{position}}{For position scales, The position of the axis.
\code{left} or \code{right} for y axes, \code{top} or \code{bottom} for x axes.}
\item{\code{super}}{The super class to use for the constructed scale}
}}
\item{low}{Colours for low and high ends of the gradient.}
\item{high}{Colours for low and high ends of the gradient.}
\item{low, high}{Colours for low and high ends of the gradient.}
\item{space}{colour space in which to calculate gradient. Must be "Lab" -
other values are deprecated.}
@ -183,14 +181,12 @@ same time, via \code{aesthetics = c("colour", "fill")}.}
\item{midpoint}{The midpoint (in data value) of the diverging scale.
Defaults to 0.}
\item{colours}{Vector of colours to use for n-colour gradient.}
\item{colours, colors}{Vector of colours to use for n-colour gradient.}
\item{values}{if colours should not be evenly positioned along the gradient
this vector gives the position (between 0 and 1) for each colour in the
\code{colours} vector. See \code{\link[scales:rescale]{rescale()}} for a convenience function
to map an arbitrary range to between 0 and 1.}
\item{colors}{Vector of colours to use for n-colour gradient.}
}
\description{
\verb{scale_*_steps} creates a two colour binned gradient (low-high),

View File

@ -99,16 +99,25 @@ labels and so forth.}
\item{alpha}{The alpha transparency, a number in [0,1], see argument alpha in
\code{\link[grDevices]{hsv}}.}
\item{begin}{The (corrected) hue in [0,1] at which the viridis colormap begins.}
\item{begin, end}{The (corrected) hue in \verb{[0,1]} at which the color map
begins and ends.}
\item{end}{The (corrected) hue in [0,1] at which the viridis colormap ends.}
\item{direction}{Sets the order of colors in the scale. If 1, the default,
colors are ordered from darkest to lightest. If -1, the order of colors is
reversed.}
\item{direction}{Sets the order of colors in the scale. If 1, the default, colors
are ordered from darkest to lightest. If -1, the order of colors is reversed.}
\item{option}{A character string indicating the colormap option to use. Four
options are available: "magma" (or "A"), "inferno" (or "B"), "plasma" (or "C"),
"viridis" (or "D", the default option) and "cividis" (or "E").}
\item{option}{A character string indicating the color map option to use.
Eight options are available:
\itemize{
\item "magma" (or "A")
\item "inferno" (or "B")
\item "plasma" (or "C")
\item "viridis" (or "D")
\item "cividis" (or "E")
\item "rocket" (or "F")
\item "mako" (or "G")
\item "turbo" (or "H")
}}
\item{aesthetics}{Character string or vector of character strings listing the
name(s) of the aesthetic(s) that this scale works with. This can be useful, for

View File

@ -69,8 +69,9 @@ the plot data. The return value must be a \code{data.frame}, and
will be used as the layer data. A \code{function} can be created
from a \code{formula} (e.g. \code{~ head(.x, 10)}).}
\item{geom}{Use to override the default connection between
\code{geom_histogram()}/\code{geom_freqpoly()} and \code{stat_bin()}.}
\item{geom}{The geometric object to use to display the data, either as a
\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the
\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})}
\item{position}{Position adjustment, either as a string naming the adjustment
(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a

View File

@ -32,18 +32,22 @@ operators which you should not have to use in simple cases.
The curly-curly operator \verb{\{\{} allows you to tunnel data-variables
passed from function arguments inside other tidy eval functions.
\verb{\{\{} is designed for individual arguments. To pass multiple
arguments contained in dots, use \code{...} in the normal way.\preformatted{my_function <- function(data, var, ...) \{
arguments contained in dots, use \code{...} in the normal way.
\if{html}{\out{<div class="sourceCode">}}\preformatted{my_function <- function(data, var, ...) \{
data \%>\%
group_by(...) \%>\%
summarise(mean = mean(\{\{ var \}\}))
\}
}
}\if{html}{\out{</div>}}
\item \code{\link[=enquo]{enquo()}} and \code{\link[=enquos]{enquos()}} delay the execution of one or several
function arguments. The former returns a single expression, the
latter returns a list of expressions. Once defused, expressions
will no longer evaluate on their own. They must be injected back
into an evaluation context with \verb{!!} (for a single expression) and
\verb{!!!} (for a list of expressions).\preformatted{my_function <- function(data, var, ...) \{
\verb{!!!} (for a list of expressions).
\if{html}{\out{<div class="sourceCode">}}\preformatted{my_function <- function(data, var, ...) \{
# Defuse
var <- enquo(var)
dots <- enquos(...)
@ -53,7 +57,7 @@ into an evaluation context with \verb{!!} (for a single expression) and
group_by(!!!dots) \%>\%
summarise(mean = mean(!!var))
\}
}
}\if{html}{\out{</div>}}
In this simple case, the code is equivalent to the usage of \verb{\{\{}
and \code{...} above. Defusing with \code{enquo()} or \code{enquos()} is only
@ -61,30 +65,36 @@ needed in more complex cases, for instance if you need to inspect
or modify the expressions in some way.
\item The \code{.data} pronoun is an object that represents the current
slice of data. If you have a variable name in a string, use the
\code{.data} pronoun to subset that variable with \code{[[}.\preformatted{my_var <- "disp"
\code{.data} pronoun to subset that variable with \code{[[}.
\if{html}{\out{<div class="sourceCode">}}\preformatted{my_var <- "disp"
mtcars \%>\% summarise(mean = mean(.data[[my_var]]))
}
}\if{html}{\out{</div>}}
\item Another tidy eval operator is \verb{:=}. It makes it possible to use
glue and curly-curly syntax on the LHS of \code{=}. For technical
reasons, the R language doesn't support complex expressions on
the left of \code{=}, so we use \verb{:=} as a workaround.\preformatted{my_function <- function(data, var, suffix = "foo") \{
the left of \code{=}, so we use \verb{:=} as a workaround.
\if{html}{\out{<div class="sourceCode">}}\preformatted{my_function <- function(data, var, suffix = "foo") \{
# Use `\{\{` to tunnel function arguments and the usual glue
# operator `\{` to interpolate plain strings.
data \%>\%
summarise("\{\{ var \}\}_mean_\{suffix\}" := mean(\{\{ var \}\}))
\}
}
}\if{html}{\out{</div>}}
\item Many tidy eval functions like \code{dplyr::mutate()} or
\code{dplyr::summarise()} give an automatic name to unnamed inputs. If
you need to create the same sort of automatic names by yourself,
use \code{as_label()}. For instance, the glue-tunnelling syntax above
can be reproduced manually with:\preformatted{my_function <- function(data, var, suffix = "foo") \{
can be reproduced manually with:
\if{html}{\out{<div class="sourceCode">}}\preformatted{my_function <- function(data, var, suffix = "foo") \{
var <- enquo(var)
prefix <- as_label(var)
data \%>\%
summarise("\{prefix\}_mean_\{suffix\}" := mean(!!var))
\}
}
}\if{html}{\out{</div>}}
Expressions defused with \code{enquo()} (or tunnelled with \verb{\{\{}) need
not be simple column names, they can be arbitrarily complex.